Первые инструменты
С одним read агент справляется, пока вы называете файл по имени.
Скажите ему «найди все TODO в проекте», и начнётся цирк: он примется наугад
открывать файлы один за другим, надеясь, что повезёт. Поиском это назвать
трудно, поэтому сегодня добавим grep. И тут же получим новую
проблему, которая будет с нами до конца курса: инструментов стало два, и
модель должна сама решать, какой брать. Самое интересное, что решает она
не по коду функции, а по тексту её описания - и этот текст мы теперь
пишем не для коллег, а для неё.
grep с понятным описанием «когда вызывать».
На поиск модель идёт в grep, на «открой вот этот файл»
в read, и всё это переключается силой docstring:
никакого роутера в вашем коде не появится.
Слова, которые встретятся
-
Docstring - строка в тройных кавычках сразу после
def. Для человека это документация, а для модели вполне рабочая инструкция: именно оттуда она узнаёт, в каких ситуациях звать этот инструмент. -
Regex (регулярное выражение) - шаблон поиска.
Бывает совсем простым, как
TODO, а бывает и повеселее:def \w+найдёт объявления функций. -
Glob - маска имени файла.
*.pyозначает «все Python-файлы», и этого хватает, чтобы не искать TODO в чужих библиотеках. -
Маршрутизация / выбор инструмента - то самое решение
модели, какую функцию вызвать. Обратите внимание: вы нигде не пишете
ifвида «если в запросе TODO, то grep». Вы пишете хорошие описания, а выбор остаётся за моделью.
Быстрый путь
- Добавьте
grep: шаблон поиска, по желанию папка и маска файлов, не больше 50 совпадений. - Опишите его блоками WHEN TO USE / WHEN NOT TO USE / DO NOT USE FOR / EXAMPLES.
- Тем же форматом обновите описание у
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 - конкретные примеры аргументов
Одного хорошего описания мало: пока read молчит про поиск,
он остаётся заманчивой альтернативой. Пусть он сам отправляет такие
запросы к grep:
"""Прочитать файл проекта. Возвращает пронумерованные строки.
WHEN TO USE: просмотр содержимого, конфигов, исходников.
WHEN NOT TO USE: поиск по нескольким файлам (используй grep).
DO NOT USE FOR: запуск команд, листинг каталогов.
"""
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 (или терминал)?