Завершаем toolbox
Читать и искать агент уже умеет, и следующее желание очевидное: пустить его
в терминал. Оттуда открывается всё сразу - ls,
git status, тесты, сборка. Ровно оттуда же одинаково легко
выполняется rm -rf по вашему рабочему каталогу, причём с самыми
добрыми намерениями: модель ведь просто «убирала лишнее». Поэтому терминал
мы выдадим, но сразу на поводке: инструмент bash плюс короткий
список того, что разрешено запускать без разговоров. Всё остальное не
выполняется, а вежливо возвращает отказ.
bash, который выполняет только безопасные команды
из белого списка. Всё остальное до subprocess не доходит:
функция возвращает текст «заблокировано», и модель обязана честно
передать это вам, а не изображать бодрый успех.
Слова, которые встретятся
-
Toolbox - весь набор инструментов агента. К концу урока
это
read,grepиbash: минимум, с которым уже можно работать по-настоящему. -
Allowlist (белый список) - перечень того, что
разрешено, а запрещено, соответственно, всё остальное.
У нас это список
SAFE_PREFIXES. -
Gate / «шлюз» - проверка перед опасным
действием, обычный шлагбаум: команда подходит - поднимаем и пропускаем,
не подходит - не запускаем и объясняем почему. Никакой библиотеки для
этого не нужно, хватит нескольких строк с
if. - Approval (подтверждение) - это когда система останавливается и спрашивает человека: «разрешить такую команду?». По-настоящему сделаем в модуле 8, а пока вместо вопроса будет честный отказ с текстом причины.
Быстрый путь
- Добавьте инструмент
bashи список разрешённых начал команд. - Если команда не из списка - не запускайте её, верните понятное сообщение.
- Проверьте: на опасный запрос модель пишет про блокировку, а не «готово, удалил».
Какие файлы трогаем
| Файл | Что делать |
|---|---|
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, то есть «перед запуском нужно
согласие человека». Выглядит как готовое решение, но флаг сам по себе
никого ни о чём не спрашивает, он только помечает вызов.
Пока вы не написали код, который реально встаёт и ждёт «да» или «нет»,
инструмент может вернуть модели невнятицу, а модель на пустом месте
допишет: «Файлы удалены». Со стороны это ровно похоже на успех, хотя
команда даже не стартовала. Такой сценарий гораздо хуже грубого,
но честного отказа.
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, и вы увидите нормальный список файлов. На втором должно
прилететь сообщение о блокировке. А вот если в ответ пришло бодрое
«готово, удалил», хотя команда и близко не запускалась - это тот самый
случай, ради которого мы возвращаем текст вместо тишины.
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.