Explorer
Explorer - самый простой из субагентов и при этом самый полезный
на старте. Он умеет читать файлы и искать по ним, и на этом его
таланты заканчиваются: ни bash, ни правок, ни
вопросов к вам. Сходил на разведку, вернулся с короткой выжимкой,
растворился. Родитель получает готовый ответ, а не сорок
промежуточных read в собственном контексте.
Именно узость и делает explorer безопасным. Нечем сломать проект, когда из инструментов у тебя только чтение и поиск.
tools_task.py с инструментом task.
На каждый вызов внутри поднимается свежий агент, у которого есть
только read и grep, а бюджет ограничен
пятью запросами к модели. Родитель отправляет разведку и получает
назад текст.
Слова, которые встретятся
-
Свежий контекст - субагент принципиально не
помнит прошлые поручения. Каждый вызов
taskэто новыйAgent.runс чистого листа, и амнезия здесь не побочный эффект, а главная фича. - UsageLimits - штука из Pydantic AI, которая ограничивает число обращений к модели за один прогон. Наш бюджет шагов и заодно страховка от субагента, который решил изучить проект целиком.
Быстрый путь
- Создать
tools_task.py- фабрикаcreate_task_tool. - Внутри - мини-агент с
read/grep, без bash. - В
main.pyзарегистрировать tooltaskу родителя. - Попросить явно делегировать разведку.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
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
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)на прогоне субагента- Ошибки возвращаются строкой
- Родитель умеет делегировать разведку и получить выжимку