MODULE_06 · УРОК 6.2

Explorer

Explorer - самый простой из субагентов и при этом самый полезный на старте. Он умеет читать файлы и искать по ним, и на этом его таланты заканчиваются: ни bash, ни правок, ни вопросов к вам. Сходил на разведку, вернулся с короткой выжимкой, растворился. Родитель получает готовый ответ, а не сорок промежуточных read в собственном контексте.

Именно узость и делает explorer безопасным. Нечем сломать проект, когда из инструментов у тебя только чтение и поиск.

ЧТО ПОЛУЧИТСЯ Файл tools_task.py с инструментом task. На каждый вызов внутри поднимается свежий агент, у которого есть только read и grep, а бюджет ограничен пятью запросами к модели. Родитель отправляет разведку и получает назад текст.

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

  • Свежий контекст - субагент принципиально не помнит прошлые поручения. Каждый вызов task это новый Agent.run с чистого листа, и амнезия здесь не побочный эффект, а главная фича.
  • UsageLimits - штука из Pydantic AI, которая ограничивает число обращений к модели за один прогон. Наш бюджет шагов и заодно страховка от субагента, который решил изучить проект целиком.

Быстрый путь

  1. Создать tools_task.py - фабрика create_task_tool.
  2. Внутри - мини-агент с read/grep, без bash.
  3. В main.py зарегистрировать tool task у родителя.
  4. Попросить явно делегировать разведку.

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

Файл Что делать
tools_task.py Создать. create_task_tool(sandbox).
main.py Править. Собрать task и добавить в tools родителя; обновить tool_names.

Шаг 1. Фабрика task

Субагенту нужны собственные read и grep. Идеи в них ровно те же, что у родительских, просто регистрируются они на другом агенте. Ниже компактный вариант, где функции живут внутри фабрики и получают песочницу через deps, так что городить лишние глобальные переменные не придётся.

tools_task.py

from pathlib import Path

from pydantic_ai import Agent, RunContext, Tool, UsageLimits

from sandbox import Sandbox

MAX_LINES = 500
MAX_MATCHES = 50


def create_task_tool(sandbox: Sandbox):
    """Вернуть async-функцию task для регистрации у родителя."""

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

        WHEN TO USE: поиск по многим файлам, сбор контекста, паттерны в коде.
        WHEN NOT TO USE: правки и команды (субагент не умеет bash/write).
        DO NOT USE FOR: решения и вопросы пользователю - это родитель.
        USAGE: description - что исследовать; ответ - краткая выжимка.
        """
        explorer = Agent(
            "deepseek:deepseek-chat",
            deps_type=Sandbox,
            instructions=(
                "Ты explorer: только исследуй и кратко отчитайся. "
                f"Рабочая директория: {sandbox.working_directory}. "
                "Не предлагай правки файлов. Не вызывай shell."
            ),
        )

        @explorer.tool
        async def read(
            sctx: RunContext[Sandbox],
            path: str,
            offset: int | None = None,
            limit: int | None = None,
        ) -> str:
            root = Path(sctx.deps.working_directory).resolve()
            abs_path = (root / path).resolve()
            if not str(abs_path).startswith(str(root)):
                return "Ошибка: путь вне рабочей директории."
            if not abs_path.is_file():
                return f"Ошибка: файл не найден: {path}"
            content = await sctx.deps.read_file(path)
            lines = content.splitlines()
            start = (offset or 1) - 1
            lines = lines[start:]
            if limit is not None:
                lines = lines[:limit]
            if len(lines) > MAX_LINES:
                lines = lines[:MAX_LINES]
                body = "\n".join(
                    f"{(offset or 1) + i}: {ln}" for i, ln in enumerate(lines)
                )
                return body + f"\n... (обрезано на {MAX_LINES} строках)"
            return "\n".join(
                f"{(offset or 1) + i}: {ln}" for i, ln in enumerate(lines)
            )

        @explorer.tool
        async def grep(
            sctx: RunContext[Sandbox],
            pattern: str,
            path: str | None = None,
            glob: str | None = None,
        ) -> str:
            import shlex

            root = Path(sctx.deps.working_directory) / (path or ".")
            root = root.resolve()
            include = glob or "*.py"
            cmd = (
                f"grep -rn --exclude-dir=.venv --exclude-dir=__pycache__ "
                f"--exclude-dir=.git --include={shlex.quote(include)} "
                f"-E {shlex.quote(pattern)} {shlex.quote(str(root))}"
            )
            result = await sctx.deps.exec(cmd)
            lines = [ln for ln in result["stdout"].strip().splitlines() if ln]
            if not lines:
                return "Совпадений нет."
            truncated = len(lines) > MAX_MATCHES
            shown = lines[:MAX_MATCHES]
            body = "\n".join(shown)
            if truncated:
                body += f"\n... ({len(lines)} всего, показаны первые {MAX_MATCHES})"
            return body

        try:
            result = await explorer.run(
                description,
                deps=ctx.deps,
                usage=ctx.usage,
                usage_limits=UsageLimits(request_limit=5),
            )
            text = result.output or "(пустой ответ субагента)"
            return f"[Explorer]\n{text}"
        except Exception as e:
            return f"Ошибка субагента: {e}"

    return task
ПОЧЕМУ СВЕЖИЙ АГЕНТ НА КАЖДЫЙ ВЫЗОВ Соблазн создать explorer один раз и переиспользовать понятен, но тогда в его истории накопятся все прошлые разведки, и мы вернёмся ровно к тому загрязнению, от которого убегали. Новый Agent и новый run дают чистый контекст, а ради него всё делегирование и затевалось.
ОШИБКИ ВОЗВРАЩАЕМ СТРОКОЙ, А НЕ ИСКЛЮЧЕНИЕМ Инструмент обязан отдать родителю строку, что бы внутри ни случилось. Пробросите исключение наружу - и вместо того, чтобы прочитать «разведка не удалась» и попробовать иначе, родитель просто рухнет вместе с субагентом. Поэтому ловим всё и возвращаем "Ошибка субагента: …".

Шаг 2. Подключить в main.py

from tools_task import create_task_tool

task_fn = create_task_tool(sandbox)

agent = Agent(
    "deepseek:deepseek-chat",
    deps_type=Sandbox,
    tools=[
        Tool(bash_fn, takes_ctx=False),
        Tool(task_fn, takes_ctx=True),
    ],
    instructions=instructions,
    # ... ProcessHistory как раньше
)

# tool_names для промпта:
tool_names = ["read", "grep", "bash", "task"]

Обратите внимание на takes_ctx=True: без него внутри task не будет ни ctx.deps с песочницей, ни ctx.usage. Второе важнее, чем кажется, - именно через него токены субагента приплюсовываются к родительским, и вы видите настоящую стоимость прогона, а не половину.

ЛОГИ ПРИ ОТЛАДКЕ Пока всё это притирается, печатайте внутри task в stderr хотя бы длину ответа субагента. Иначе родитель однажды сообщит «субагент ничего не нашёл», и вы не сможете отличить пустую выдачу от прогона, который вообще не состоялся.

Проверьте

uv run python main.py . "Делегируй субагенту через task: найди все места, где импортируется pathlib, и перечисли файлы. Сам grep не вызывай - только task."

Родитель должен дёрнуть task и получить обратно выжимку от explorer. Самое интересное тут не в ответе, а в том, чего в контексте родителя нет: простыня всех совпадений осталась внутри субагента и умерла вместе с ним.

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

  • Есть tools_task.py с create_task_tool
  • На каждый вызов создаётся новый explorer
  • У explorer только read и grep
  • UsageLimits(request_limit=5) на прогоне субагента
  • Ошибки возвращаются строкой
  • Родитель умеет делегировать разведку и получить выжимку