MODULE_01 · УРОК 1.3

Завершаем toolbox

Читать и искать агент уже умеет, и следующее желание очевидное: пустить его в терминал. Оттуда открывается всё сразу - ls, git status, тесты, сборка. Ровно оттуда же одинаково легко выполняется rm -rf по вашему рабочему каталогу, причём с самыми добрыми намерениями: модель ведь просто «убирала лишнее». Поэтому терминал мы выдадим, но сразу на поводке: инструмент bash плюс короткий список того, что разрешено запускать без разговоров. Всё остальное не выполняется, а вежливо возвращает отказ.

ЧТО ПОЛУЧИТСЯ Инструмент bash, который выполняет только безопасные команды из белого списка. Всё остальное до subprocess не доходит: функция возвращает текст «заблокировано», и модель обязана честно передать это вам, а не изображать бодрый успех.

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

  • Toolbox - весь набор инструментов агента. К концу урока это read, grep и bash: минимум, с которым уже можно работать по-настоящему.
  • Allowlist (белый список) - перечень того, что разрешено, а запрещено, соответственно, всё остальное. У нас это список SAFE_PREFIXES.
  • Gate / «шлюз» - проверка перед опасным действием, обычный шлагбаум: команда подходит - поднимаем и пропускаем, не подходит - не запускаем и объясняем почему. Никакой библиотеки для этого не нужно, хватит нескольких строк с if.
  • Approval (подтверждение) - это когда система останавливается и спрашивает человека: «разрешить такую команду?». По-настоящему сделаем в модуле 8, а пока вместо вопроса будет честный отказ с текстом причины.

Быстрый путь

  1. Добавьте инструмент bash и список разрешённых начал команд.
  2. Если команда не из списка - не запускайте её, верните понятное сообщение.
  3. Проверьте: на опасный запрос модель пишет про блокировку, а не «готово, удалил».

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

Файл Что делать
main.py Править. Добавить bash с белым списком префиксов и gate перед запуском.
read / grep Не трогать в этом уроке.

Упражнение 1.3

  • Список вроде: ls, pwd, git status, git log, git diff - в основном команды «посмотреть», а не «сломать».
  • Сравнивайте по началу строки: ls -la начинается с ls - значит, подходит.
  • Поставьте таймаут (например 30 секунд), чтобы зависшая команда не держала агента вечно.
  • В docstring снова: WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR - чтобы модель не читала файлы через cat, а шла в read.

Почему не включаем «спросить пользователя» прямо сейчас

В Pydantic AI у инструмента есть соблазнительный флаг requires_approval=True, то есть «перед запуском нужно согласие человека». Выглядит как готовое решение, но флаг сам по себе никого ни о чём не спрашивает, он только помечает вызов. Пока вы не написали код, который реально встаёт и ждёт «да» или «нет», инструмент может вернуть модели невнятицу, а модель на пустом месте допишет: «Файлы удалены». Со стороны это ровно похоже на успех, хотя команда даже не стартовала. Такой сценарий гораздо хуже грубого, но честного отказа.

ВАЖНО «Нужно approval» ≠ готовая защита. Без вашего диалога с пользователем пометка бесполезна. Поэтому в этом уроке проверка стоит прямо в теле bash: не в списке → сразу вернуть строку с причиной. Спросить «разрешить?» научимся в модуле 8.

Проверка прямо в коде инструмента

Логика до неприличия простая: перед тем как дёрнуть subprocess, мы смотрим на команду. Подходит - запускаем, не подходит - возвращаем строку с объяснением. Второй случай тут важнее первого: эта строка уходит обратно в диалог как обычный результат инструмента, модель её читает и может пересказать вам как есть, без творчества.

фрагмент для main.py (добавьте к read и grep)

import subprocess
from pathlib import Path

from pydantic_ai import Agent, RunContext

# Белый список: команда должна НАЧИНАТЬСЯ с одной из этих строк
SAFE_PREFIXES = [
    "ls", "cat", "echo", "pwd", "which", "find",
    "head", "tail", "wc",
    "git log", "git status", "git diff",
]

def is_safe(command: str) -> bool:
    cmd = command.strip()
    return any(cmd.startswith(prefix) for prefix in SAFE_PREFIXES)

@agent.tool
def bash(ctx: RunContext[Path], command: str) -> str:
    """Выполнить shell-команду в рабочей директории.

    WHEN TO USE: сборка, тесты, git, список файлов в каталоге.
    WHEN NOT TO USE: чтение известного файла (используй read);
      поиск по тексту в проекте (используй grep).
    DO NOT USE FOR: чтение файлов (read), поиск по коду (grep).
    """
    if not is_safe(command):
        allowed = ", ".join(SAFE_PREFIXES)
        return (
            f'Заблокировано: "{command}" не из белого списка. '
            f"Автоматически можно только: {allowed}."
        )
    try:
        proc = subprocess.run(
            command,
            shell=True,
            cwd=ctx.deps,
            capture_output=True,
            text=True,
            timeout=30,
        )
        out = (proc.stdout or "") + (proc.stderr or "")
        if proc.returncode != 0:
            return f"Exit {proc.returncode}: {out.strip()}"
        return out.strip() or "(нет вывода)"
    except subprocess.TimeoutExpired:
        return "Таймаут: команда дольше 30 секунд."

Запомните главное правило этого урока: при блокировке вы всё равно что-то возвращаете, пусть даже одну скучную строку. Не молчите и не «проглатывайте» вызов. У модели тогда на руках факт, а не дыра, которую она с удовольствием заполнит фантазией.

Проверьте

uv run python main.py . "Перечисли файлы в этой директории"
uv run python main.py . "Выполни команду: rm -rf .venv"

На первом запросе агент возьмёт что-нибудь вроде ls или find, и вы увидите нормальный список файлов. На втором должно прилететь сообщение о блокировке. А вот если в ответ пришло бодрое «готово, удалил», хотя команда и близко не запускалась - это тот самый случай, ради которого мы возвращаем текст вместо тишины.

ОБХОДЫ Настойчиво попросите «удали .venv», и модель начнёт изобретать: find … -exec rm … вместо честного rm. Наша проверка «начинается с» ловит прямой rm, но не каждый трюк через find. В боевых системах списки заметно сложнее, там и опасные шаблоны, и regex. Мы намеренно оставляем простой вариант: сейчас важно понять, зачем нужна проверка, а не закрыть все щели за один урок.

Три инструмента - один агент

Инструмент Зачем Как не навредить
read Читать файл Не больше 500 строк за раз
grep Искать по проекту Не больше 50 совпадений
bash Команды в терминале Только из белого списка

Три инструмента, три разные страховки, и каждая на своём месте: docstring подсказывает модели, какой инструмент взять, лимиты берегут память диалога, а белый список - ваш диск. Дальше в курсе набор будет расти, но эта троица останется скелетом.

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

  • Безопасные команды (ls, git status) реально выполняются через bash
  • Запрос «прочитай файл» по-прежнему идёт в read, а не в bash + cat
  • rm -rf, sudo и прочее вне списка возвращают текст блокировки
  • Модель сообщает о блокировке, а не притворяется, что команда прошла
НА ПОТОМ Жёсткий отказ честен, но груб. Удобнее спросить: «Агент хочет выполнить pip install X. Разрешить?» Да - выполнить и вернуть вывод. Нет - вернуть «пользователь отказал». Это как раз сценарий с approval из модуля 8.