MODULE_06 · УРОК 6.3

Executor

Explorer собирает факты и ничего не трогает, поэтому с ним легко: худшее, что он может, - потратить ваши токены. Executor устроен иначе, он действует. У него есть bash, больше шагов на работу и, соответственно, куда больше способов испортить вечер. Значит и обращаться с ним нужно строже.

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

ЧТО ПОЛУЧИТСЯ У инструмента task появится аргумент subagent_type со значениями "explorer" и "executor". Второй получит те же read и grep плюс собственный bash в режиме delegated с коротким списком доверенных команд.

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

  • Delegated trust - тот самый режим проверки из модуля 2: разрешены ровно команды из списка trust, всё остальное блокируется без обсуждения. Спросить разрешения субагенту не у кого, поэтому решение принимается заранее и списком.
  • Инструкция для executor - цель, шаги, ограничения и способ проверить результат. Размытое «почини баг» explorer бы просто пережил, а executor воспримет как приглашение к творчеству.

Быстрый путь

  1. В tools_task.py добавить параметр subagent_type.
  2. Ветка executor: create_bash_tool + create_approval({"mode": "delegated", "trust": [...]}).
  3. Лимит запросов - 15. Обновить docstring tool.

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

Файл Что делать
tools_task.py Править. Роутинг explorer/executor.
main.py Обычно не трогать, если task уже зарегистрирован.

Шаг 1. Расширить сигнатуру task

async def task(
    ctx: RunContext[Sandbox],
    description: str,
    subagent_type: str = "explorer",
) -> str:
    """Делегировать работу субагенту.

    Explorer (по умолчанию): только read/grep, короткий бюджет.
    Executor: read/grep + bash в delegated (trust-список).

    WHEN TO USE: разведка по многим файлам (explorer);
      узкая работа с командами под trust (executor).
    WHEN NOT TO USE: неясные требования и архитектура - решает родитель.
    """

Шаг 2. Ветка executor

Ключевой момент: bash у executor свой, а не родительский. И дело не в чистоте архитектуры. Родительский bash работает в интерактивном режиме и в непонятной ситуации спрашивает человека, а перед субагентом никакого человека нет - он повиснет в ожидании ответа, которого не будет. Поэтому собираем отдельный инструмент с проверкой в режиме delegated.

from approval import create_approval
from tools_bash import create_bash_tool

if subagent_type == "executor":
    executor_bash = create_bash_tool(
        ctx.deps,
        create_approval({
            "mode": "delegated",
            "trust": [
                "pytest",
                "uv run pytest",
                "python -m pytest",
                "git status",
                "git diff",
                "ls",
                "pwd",
            ],
        }),
    )
    executor = Agent(
        "deepseek:deepseek-chat",
        deps_type=Sandbox,
        tools=[Tool(executor_bash, takes_ctx=False)],
        instructions=(
            "Ты executor: выполняй инструкцию точно. "
            f"Рабочая директория: {ctx.deps.working_directory}. "
            "Не задавай вопросов. Не исследуй лишнее. Сделай и отчитайся."
        ),
    )
    # повесьте на executor те же read/grep, что у explorer
    # (те же read/grep, что у explorer - в уроке 6.4 вынесем в отдельную функцию)


    try:
        result = await executor.run(
            description,
            deps=ctx.deps,
            usage=ctx.usage,
            usage_limits=UsageLimits(request_limit=15),
        )
        return f"[Executor]\n{result.output or '(пусто)'}"
    except Exception as e:
        return f"Ошибка executor: {e}"

# иначе - прежний explorer…
ПОКА НЕТ write И edit Отдельного инструмента для правки файлов у нас в курсе ещё нет, так что executor силён ровно там, где хватает доверенных команд: прогнать тесты, посмотреть git status, глянуть листинг. Массовый рефакторинг подождёт появления write - роль от этого не изменится, просто инструментов в руках станет больше.

Сравнение ролей

Explorer Executor
Tools read, grep read, grep, bash (delegated)
Лимит запросов 5 15
Может менять мир нет только через trust bash
Спрашивает вас нет нет

Качество инструкции

Разница между ролями чувствуется именно здесь. Explorer простит вам размытую формулировку: в худшем случае принесёт не то, что вы имели в виду. Executor же понимает инструкцию буквально и начинает действовать, так что цена неточности другая.

Плохо: «Почини тесты.»

Лучше: «Запусти pytest. Если упало - опиши первые ошибки из вывода. Файлы не меняй.»

Проверьте

uv run python main.py . "Делегируй executor через task (subagent_type=executor): выполни pytest в проекте и кратко отчитайся. Если pytest нет - так и скажи."

Родитель должен выбрать executor, а всё, что не попало в trust, будет заблокировано ровно так же, как в модуле 2. Для контраста попробуйте ту же просьбу без subagent_type: explorer вежливо расскажет, что тесты запустить не может, потому что shell ему не выдали.

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

  • У task есть subagent_type
  • Executor с bash в delegated и коротким trust
  • Лимит запросов executor - 15
  • Explorer из 6.2 не сломан
  • Ошибки по-прежнему строкой