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решает, кого поднимать.
Быстрый путь
- Открыть только
tools_task.py. - Кусок «создать explorer» → функция
build_explorer. - Кусок «создать executor» → функция
build_executor. - Кусок
try: … agent.run …→ функцияrun_subagent. - В
taskоставить короткийif. - Прогнать промпт внизу.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
tools_task.py |
Править. Единственный файл этого урока. |
main.py |
Не трогать. create_task_tool(sandbox) уже подключён в 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 о нашем переезде
даже не узнает.
Порядок в файле (сверху вниз)
- импорты, константы;
_attach_read_grep(если есть);build_explorer;build_executor;run_subagent;create_task_toolс короткойtask.
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не меняли- Промпт с двумя делегированиями отрабатывает
- Ошибки субагента по-прежнему возвращаются строкой