Шлюз подтверждения
В create_bash_tool сейчас прошит один единственный закон:
нет в белом списке - значит стоп. Дома за клавиатурой это правильно, а вот
в CI такой агент встанет намертво, потому что нажать «ОК» там некому.
Субагенту, наоборот, вся ваша власть ни к чему: пусть ходит по короткому
поводку. Получается, политика зависит от того, кто и где запускает агента,
и держать её внутри инструмента больше нельзя. Сегодня вынесем решение
в отдельный approval.py, подключим его в
tools_bash.py и научимся переключать три режима одной строкой
в main.py.
approval.py + правка tools_bash.py +
пара строк в main.py. Меняете
{"mode": "interactive"} на
"background" или "delegated" -
и та же команда то проходит, то блокируется.
Слова, которые встретятся
-
needs_approval(command) - функция, которая отвечает на
один вопрос: нужно ли для этой команды разрешение человека.
Trueозначает «не запускай, верни текст блокировки»,False- «можно смело отдавать в subprocess». - Режим (mode) - настройка, по которой эта функция принимает решение. У нас их три: дома за клавиатурой, в CI без человека и для субагента с урезанными правами.
Быстрый путь
- Создать
approval.py. - В
tools_bash.pyзаменить аргументsafe_prefixesнаneeds_approval. - В
main.pyсобратьcreate_approval(...)→create_bash_tool(...). - Прогнать две команды в разных режимах.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
approval.py |
Создать. Типы конфига + create_approval + список SAFE_PREFIXES. |
tools_bash.py |
Править. Сигнатура фабрики: вместо списка префиксов - функция needs_approval. |
main.py |
Править. Импорты, вызов create_approval, передать результат в create_bash_tool. |
local_bash.py |
Не трогать. Он по-прежнему только крутит subprocess. |
Шаг 1. Создайте approval.py
Новый файл кладём рядом с main.py. Внутри только белый список
и решение «блокировать или нет»: ни subprocess, ни агента,
ни малейшего представления о том, кто эту политику будет применять.
Такой файл потом приятно читать и легко тестировать.
approval.py (целиком)
from collections.abc import Callable
from typing import Literal, TypedDict
class InteractiveConfig(TypedDict):
mode: Literal["interactive"]
class BackgroundConfig(TypedDict):
mode: Literal["background"]
class DelegatedConfig(TypedDict):
mode: Literal["delegated"]
trust: list[str]
ApprovalConfig = InteractiveConfig | BackgroundConfig | DelegatedConfig
# Общий белый список для режима interactive (дома за клавиатурой)
SAFE_PREFIXES = [
"ls", "cat", "echo", "pwd", "which", "find",
"head", "tail", "wc",
"git log", "git status", "git diff",
]
def create_approval(config: ApprovalConfig) -> Callable[[str], bool]:
"""Вернуть функцию needs_approval(command) -> bool."""
def needs_approval(command: str) -> bool:
cmd = command.strip()
# CI: человека нет - пускаем всё (осознанный риск)
if config["mode"] == "background":
return False
# Субагент: только то, что дали в trust
if config["mode"] == "delegated":
allowed = config["trust"]
return not any(cmd.startswith(p) for p in allowed)
# interactive: как старый белый список
return not any(cmd.startswith(p) for p in SAFE_PREFIXES)
return needs_approval
Если продраться через типы, вся суть файла сводится к трём строчкам поведения:
interactive- можно то, что вSAFE_PREFIXES; остальное блок.background- можно всё (для CI).delegated- можно только строки изtrust.
Шаг 2. Поправьте tools_bash.py
Политика написана, но пока никто её не спрашивает. После урока 2.2 в фабрике у вас примерно такая картина:
def create_bash_tool(
operations: BashOperations,
safe_prefixes: list[str],
) -> Callable[..., str]:
def is_safe(command: str) -> bool:
...
async def bash(command: str) -> str:
if not is_safe(command):
return "Заблокировано..."
...
Меняем немного: второй аргумент теперь не список, а готовая функция из
approval.py. Фабрика перестаёт разбираться в префиксах
самостоятельно и просто спрашивает у политики разрешения:
tools_bash.py - новая сигнатура фабрики
from collections.abc import Callable
# ExecResult, BashOperations - как были в уроке 2.2
def create_bash_tool(
operations: BashOperations,
needs_approval: Callable[[str], bool], # было: safe_prefixes: list[str]
) -> Callable[..., str]:
async def bash(command: str) -> str:
"""Выполнить shell-команду в рабочей директории.
... ваш полный docstring из 2.1 ...
"""
if needs_approval(command):
return (
f'Заблокировано: "{command}" требует подтверждения '
f"(режим политики в main.py)."
)
result = await operations.exec(command)
return result["stdout"] or "(нет вывода)"
return bash
create_bash_tool(local_ops, SAFE_PREFIXES) в
main.py стала невалидной: там ждут функцию, а вы отдаёте
список. В лучшем случае получите TypeError, в худшем - молчаливо
странное поведение. Так что шаг 3 делайте сразу, не откладывая.
Шаг 3. Соберите всё в main.py
Найдите место, где вы делали
create_bash_tool(local_ops, SAFE_PREFIXES),
и замените на:
main.py - фрагмент
from local_bash import LocalBashOps
from tools_bash import create_bash_tool
from approval import create_approval
from pydantic_ai import Agent, Tool
# ... cwd как раньше ...
local_ops = LocalBashOps(cwd)
# Переключайте ТОЛЬКО эту строку, чтобы менять поведение:
needs_approval = create_approval({"mode": "interactive"})
# needs_approval = create_approval({"mode": "background"})
# needs_approval = create_approval({
# "mode": "delegated",
# "trust": ["pwd", "find", "git status"],
# })
bash_fn = create_bash_tool(local_ops, needs_approval)
agent = Agent(
"deepseek:deepseek-chat",
deps_type=Path,
# Один способ зарегистрировать bash - через tools=[...]
tools=[Tool(bash_fn, takes_ctx=False)],
instructions=...,
)
# read / grep - как раньше, через @agent.tool ниже
# НЕ вызывайте ещё и agent.tool_plain(bash_fn): будет конфликт имени 'bash'
tools=[Tool(bash_fn, takes_ctx=False)] при создании
Agent, или позже
agent.tool_plain(bash_fn). Достаточно одного варианта.
Если уже есть tools=[Tool(bash_fn, ...)], строка
agent.tool_plain(bash_fn) не нужна - иначе снова
Tool name conflicts: 'bash'.
И приберитесь за собой: SAFE_PREFIXES вместе со старой
функцией is_safe из main.py нужно удалить.
Список переехал в approval.py, а is_safe теперь
вообще никто не вызывает. Оставите - и через неделю будете гадать, какая
же из двух копий белого списка работает.
main.py: поведение агента
меняется ею целиком, без трёх почти одинаковых функций по копипасте.
А когда позже захочется читать эту настройку из конфига или выдавать
субагенту его собственную, код политики уже будет готов и проверен.
Проверьте
Самое приятное в этом уроке - проверка: политику видно сразу, без
погружения в код. Оставьте mode: "interactive" и выполните:
uv run python main.py . "Выполни: git status"
uv run python main.py . "Выполни: pip install requests"
Первая команда пройдёт, её префикс есть в SAFE_PREFIXES.
Вторая вернёт текст блокировки, и никакой пакет никуда не установится.
Теперь фокус. Закомментируйте interactive, раскомментируйте
background и повторите pip install requests:
тот же агент, тот же инструмент, а шлюз пропускает. Если команда после
этого сама свалится с ошибкой, к политике это уже не имеет отношения.
Осталось попробовать delegated с
trust: ["git status"], и картина станет полной:
git status проходит, pip install requests
блокируется. Три разных мира, одна строка разницы.
pytest всё равно красный? Значит
упали тесты, а не политика: пропустить команду и выполнить её удачно -
это два независимых события. Смотрите на exit_code отдельно
от решения шлюза, иначе будете чинить не то.
Готово, если:
- Есть файл
approval.pyсcreate_approval - В
tools_bash.pyфабрика принимаетneeds_approval, а не список префиксов - В
main.pybash собран черезcreate_approval+create_bash_tool - В
interactive:git statusпроходит,pip install- блок - Переключение на
background/delegatedменяет поведение без правки фабрики
needs_approval вернул
True, мы не молчим, а обязательно что-то отдаём модели.