MODULE_01 · УРОК 1.2

Первые инструменты

С одним read агент справляется, пока вы называете файл по имени. Скажите ему «найди все TODO в проекте», и начнётся цирк: он примется наугад открывать файлы один за другим, надеясь, что повезёт. Поиском это назвать трудно, поэтому сегодня добавим grep. И тут же получим новую проблему, которая будет с нами до конца курса: инструментов стало два, и модель должна сама решать, какой брать. Самое интересное, что решает она не по коду функции, а по тексту её описания - и этот текст мы теперь пишем не для коллег, а для неё.

ЧТО ПОЛУЧИТСЯ Инструмент grep с понятным описанием «когда вызывать». На поиск модель идёт в grep, на «открой вот этот файл» в read, и всё это переключается силой docstring: никакого роутера в вашем коде не появится.

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

  • Docstring - строка в тройных кавычках сразу после def. Для человека это документация, а для модели вполне рабочая инструкция: именно оттуда она узнаёт, в каких ситуациях звать этот инструмент.
  • Regex (регулярное выражение) - шаблон поиска. Бывает совсем простым, как TODO, а бывает и повеселее: def \w+ найдёт объявления функций.
  • Glob - маска имени файла. *.py означает «все Python-файлы», и этого хватает, чтобы не искать TODO в чужих библиотеках.
  • Маршрутизация / выбор инструмента - то самое решение модели, какую функцию вызвать. Обратите внимание: вы нигде не пишете if вида «если в запросе TODO, то grep». Вы пишете хорошие описания, а выбор остаётся за моделью.

Быстрый путь

  1. Добавьте grep: шаблон поиска, по желанию папка и маска файлов, не больше 50 совпадений.
  2. Опишите его блоками WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR / EXAMPLES.
  3. Тем же форматом обновите описание у read, чтобы он «отталкивал» поиск.

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

Файл Что делать
main.py Править. Добавить grep; обновить docstring у read (WHEN NOT / DO NOT).

Упражнение 1.2

  • Аргументы: pattern, опционально path и glob.
  • Внутри - системная команда grep через subprocess. Не лезьте в .venv, __pycache__, .git (там шум, не ваш код).
  • Если совпадений больше 50 - покажите первые 50 и напишите, сколько было всего.
  • «Ничего не найдено» - нормальный успешный ответ, а не авария программы.

Плохое описание → плохой выбор

Прежде чем писать правильно, полезно один раз написать нарочно плохо. Сделайте описание из двух слов и посмотрите, куда модель пойдёт:

main.py

@agent.tool
def grep(ctx: RunContext[Path], pattern: str, glob: str | None = None) -> str:
    """Search files."""
    ...

Terminal

uv run python main.py . "Найди все TODO-комментарии в проекте"

Скорее всего, grep она просто проигнорирует и полезет читать файлы через read, а когда у неё появится терминал, будет рваться в bash. И винить тут особо некого: по двум словам «Search files» выбрать нельзя, остаётся угадывать.

Описание - это подсказка модели, не «для документации»

Первая реакция обычно такая: «сейчас поправлю логику поиска». Но код-то рабочий, а сломан текст, который читает модель. Вот с него и начнём:

фрагмент grep для main.py

@agent.tool
def grep(
    ctx: RunContext[Path],
    pattern: str,
    path: str | None = None,
    glob: str | None = None,
) -> str:
    """Поиск по содержимому файлов через regex. Строки с путями.

    WHEN TO USE: паттерны по многим файлам, определения функций,
      импорты, TODO, сообщения об ошибках.
    WHEN NOT TO USE: чтение уже известного файла (используй read).
    DO NOT USE FOR: запуск команд, листинг каталогов.
    EXAMPLES:
      - TODO: pattern "TODO" glob "*.py"
      - определения функций: pattern "def \\w+" glob "*.py"
    """
    import shlex
    import subprocess

    root = (ctx.deps / (path or ".")).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))}"
    )
    try:
        proc = subprocess.run(
            cmd, shell=True, capture_output=True, text=True, timeout=10
        )
        lines = [ln for ln in proc.stdout.strip().splitlines() if ln]
    except subprocess.TimeoutExpired:
        return "Таймаут: поиск занял слишком много времени."

    if not lines:
        return "Совпадений нет."

    MAX_MATCHES = 50
    truncated = len(lines) > MAX_MATCHES
    shown = lines[:MAX_MATCHES]
    body = "\n".join(shown)
    if truncated:
        body += f"\n... ({len(lines)} всего, показаны первые {MAX_MATCHES})"
    return body

Кода поиска тут всего десяток строк, вся работа ушла в описание. Разберём, зачем каждый блок:

  • WHEN TO USE - «зови меня, если…»
  • WHEN NOT TO USE - «в этой ситуации лучше другой инструмент»
  • DO NOT USE FOR - ещё раз жёстко: чем этим инструментом не решают задачу
  • EXAMPLES - конкретные примеры аргументов
ТЯГА К ТЕРМИНАЛУ У DeepSeek, да и у большинства моделей, при слабых описаниях включается рефлекс: «а давайте просто выполним команду в shell». Поэтому запрет пишут дважды, в WHEN NOT TO USE и в DO NOT USE FOR. Выглядит как перестраховка, но одного раза модели обычно мало.

Одного хорошего описания мало: пока read молчит про поиск, он остаётся заманчивой альтернативой. Пусть он сам отправляет такие запросы к grep:

"""Прочитать файл проекта. Возвращает пронумерованные строки.
WHEN TO USE: просмотр содержимого, конфигов, исходников.
WHEN NOT TO USE: поиск по нескольким файлам (используй grep).
DO NOT USE FOR: запуск команд, листинг каталогов.
"""
ЗАЧЕМ ПОТОЛОК 50 СОВПАДЕНИЙ Поищите без лимита что-нибудь вроде import по большому проекту, и вам прилетят сотни строк. Чтобы ответить на вопрос «где тут TODO», модели хватает пятидесяти; пятьсот - это уже просто мусор, который до конца сессии болтается в контексте.

Проверьте

Положите в маленький файл пару строк с # TODO:, затем:

uv run python main.py . "Найди все TODO-комментарии в проекте"
uv run python main.py . "Прочитай pyproject.toml"

Первый запрос должен уйти в grep, второй в read. Если оба раза срабатывает один и тот же инструмент, не бросайтесь править логику: почти всегда лечится текстом описания, а не кодом.

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

  • «Найди TODO» вызывает grep, а не read
  • «Прочитай pyproject.toml» вызывает read
  • grep отдаёт не больше 50 строк и пишет, сколько было всего, если обрезал
  • У обоих инструментов в описании есть WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR
ЭКСПЕРИМЕНТ Портьте описание grep по кусочкам: сначала уберите EXAMPLES, потом DO NOT USE FOR, потом WHEN NOT TO USE. На каком шаге модель снова начинает угадывать через read (или терминал)?