MODULE_06 · УРОК 6.4

Task tool

Загляните в tools_task.py после двух прошлых уроков. Скорее всего, там одна героическая функция task, в которой живёт и explorer, и executor, и два почти одинаковых вызова agent.run с обработкой ошибок. Работает оно прекрасно, а вот читается уже не очень - и добавить третью роль в такое, не сломав две существующие, будет квестом.

Поэтому сегодня никакой новой функциональности. Мы просто разложим один файл по функциям с внятными именами: поведение останется прежним, main.py не узнает, что что-то изменилось.

ЧТО ПОЛУЧИТСЯ В tools_task.py появятся три отдельные функции: build_explorer, build_executor и run_subagent. Сама task ужмётся до нескольких строк: посмотрела на subagent_type, позвала нужную сборку, вернула текст.

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

  • Разрезать файл на функции - никакой магии и никаких паттернов из книжек. Вы буквально вырезаете кусок кода из середины task, вставляете выше под собственным именем и зовёте это имя оттуда, откуда вырезали.
  • subagent_type - аргумент инструмента, строка "explorer" или "executor". Именно по ней task решает, кого поднимать.

Быстрый путь

  1. Открыть только tools_task.py.
  2. Кусок «создать explorer» → функция build_explorer.
  3. Кусок «создать executor» → функция build_executor.
  4. Кусок try: … agent.run … → функция run_subagent.
  5. В task оставить короткий if.
  6. Прогнать промпт внизу.

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

Файл Что делать
tools_task.py Править. Единственный файл этого урока.
main.py Не трогать. create_task_tool(sandbox) уже подключён в 6.2.
ЕСЛИ В main.py ЕЩЁ НЕТ task Вернитесь и доделайте урок 6.2. В main.py должны быть импорт create_task_tool, строка task_fn = create_task_tool(sandbox) и Tool(task_fn, takes_ctx=True) в списке инструментов. Сегодняшний урок туда не добавляет ничего, так что пропустить 6.2 и надеяться на лучшее не выйдет.
НЕ УДАЛЯЙТЕ КОД СОЗДАНИЯ АГЕНТОВ Мы блоки переносим, а не выбрасываем. Классическая ошибка: стереть из task создание Agent, написать вместо него build_explorer(...) и забыть, что самой функции ещё нет. Python встретит вас бодрым NameError. Read и grep, а если вы их уже вынесли - то и _attach_read_grep, тоже никуда из файла не деваются.

Шаг 1. Функция build_explorer

В tools_task.py над create_task_tool создайте функцию. В тело вырежьте из task всё, что создаёт explorer (Agent + read/grep), и в конце напишите return explorer.

tools_task.py - вставить над create_task_tool

def build_explorer(sandbox: Sandbox) -> Agent:
    explorer = Agent(
        "deepseek:deepseek-chat",
        deps_type=Sandbox,
        instructions=(
            "Ты explorer: только исследуй и кратко отчитайся. "
            f"Рабочая директория: {sandbox.working_directory}. "
            "Не предлагай правки файлов. Не вызывай shell."
        ),
    )
    _attach_read_grep(explorer)  # если read/grep у вас прямо в task - перенесите их сюда же
    return explorer

Шаг 2. Функция build_executor

Рядом делаем ровно то же самое для executor: bash в режиме delegated, сам Agent, те же read с grep и return executor в конце. Ничего нового придумывать не нужно, весь текст берётся из вашей ветки if subagent_type == "executor" из прошлого урока.

tools_task.py

def build_executor(sandbox: Sandbox) -> Agent:
    executor_bash = create_bash_tool(
        sandbox,
        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"Рабочая директория: {sandbox.working_directory}. "
            "Не задавай вопросов. Не исследуй лишнее. Сделай и отчитайся."
        ),
    )
    _attach_read_grep(executor)
    return executor

Шаг 3. Функция run_subagent

Дальше самое приятное. У вас в файле два почти близнецовых куска try: result = await …run(…), отличающихся лимитом и подписью. Оставляем один, общий. Параметр role тут ничего не решает по сути - это просто строка, из которой берётся лимит запросов и префикс в ответе, [explorer] или [executor].

async def run_subagent(role: str, agent: Agent, description: str, ctx) -> str:
    try:
        limit = 15 if role == "executor" else 5
        result = await agent.run(
            description,
            deps=ctx.deps,
            usage=ctx.usage,
            usage_limits=UsageLimits(request_limit=limit),
        )
        text = result.output or f"(пустой ответ от {role})"
        return f"[{role}]\n{text}"
    except Exception as e:
        return f"Ошибка {role}: {e}"

Шаг 4. Укоротить саму task

Теперь task внутри create_task_tool никого не создаёт руками. От неё осталось только решение, кого звать, и сам вызов. Зато docstring никуда не делся: для модели это по-прежнему главный документ, объясняющий, когда этим инструментом вообще стоит пользоваться.

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

        Explorer: разведка read/grep, короткий бюджет.
        Executor: то же + bash в delegated по trust-списку.

        WHEN TO USE: многофайловый поиск (explorer); узкий прогон команд (executor).
        WHEN NOT TO USE: архитектура и неясные требования - родитель.
        DO NOT USE FOR: задача в один шаг, которую родитель сделает сам.
        """
        if subagent_type == "executor":
            agent = build_executor(ctx.deps)
            return await run_subagent("executor", agent, description, ctx)
        agent = build_explorer(ctx.deps)
        return await run_subagent("explorer", agent, description, ctx)

    return task

Снаружи ничего не поменялось: имя create_task_tool прежнее, возвращает она всё ту же task. Ради этого мы и городили фабрику - main.py о нашем переезде даже не узнает.

Порядок в файле (сверху вниз)

  1. импорты, константы;
  2. _attach_read_grep (если есть);
  3. build_explorer;
  4. build_executor;
  5. run_subagent;
  6. create_task_tool с короткой task.
ЗАЧЕМ ТАК Проверить пользу легко на мысленном эксперименте. Захочется завтра третью роль, скажем reviewer, - это новая функция build_reviewer и одна дополнительная ветка в if. Ни одна существующая строчка не пострадает, и гигантская task обратно не отрастёт.

На потом (сейчас делать не нужно)

Есть ещё одна тема, о которой стоит знать заранее, но которую сегодня трогать рано. Когда субагенты сами начнут вызывать task, встанет вопрос, кому позволено кого порождать, - иначе explorer однажды заведёт себе explorer, и так до конца бюджета. Набросок ниже копировать не обязательно, просто запомните, что такая ручка бывает.

# необязательный набросок
SPAWN_PERMISSIONS = {
    "orchestrator": ["explorer", "executor"],
    "executor": ["explorer"],
    "explorer": [],
}

Проверьте

uv run python main.py . "Сначала через task (explorer) найди, какие файлы импортируют approval. Потом через task (executor) запусти git status и кратко скажи, чистое ли дерево."

Уйти должны два вызова task с разными значениями subagent_type, а результат - выглядеть точно так же, как до рефакторинга. Это и есть критерий успеха. Откройте tools_task.py и полюбуйтесь: внизу короткая task, выше три самостоятельные функции.

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

  • В файле есть build_explorer, build_executor, run_subagent
  • Внутри task нет длинного создания Agent - только if и вызовы
  • main.py не меняли
  • Промпт с двумя делегированиями отрабатывает
  • Ошибки субагента по-прежнему возвращаются строкой
ДАЛЬШЕ МОДУЛЬ 7 Субагент живёт один короткий прогон и умирает без сожалений. С облачной песочницей так не выйдет: она живёт минутами, засыпает по таймеру и вообще имеет собственное мнение о вашем расписании. Следующий модуль про её жизненный цикл, и там будет больше разбора идей, чем копирования кода.