MODULE_01 · УРОК 1.1

От чата к агенту

Попросите модель «посмотреть» ваш pyproject.toml, и она с самым уверенным видом перечислит: имя проекта, версия, пара зависимостей. Звучит правдоподобно, только файл она не открывала и открыть не может: у неё нет ни рук, ни доступа к вашему диску, зато есть отличная память на то, как такие файлы обычно выглядят. Это ещё не агент, это вежливый угадыватель. Сегодня мы дадим ему один настоящий инструмент, самую обычную Python-функцию чтения файла, и разница будет видна с первого запуска: вместо «там обычно бывает» в ответе появятся пронумерованные строки из вашего проекта.

ЧТО ПОЛУЧИТСЯ Небольшой скрипт на Pydantic AI: по вашей фразе модель вызывает инструмент read, реально читает файл с диска и отвечает уже по фактам, а не по догадкам.

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

  • Чатбот - модель, которая умеет только говорить. Ни файлов, ни терминала, ни поиска: всё, что она выдаёт, собрано из прочитанного когда-то раньше.
  • Агент - та же самая модель, но с руками. Руки - это инструменты (tools), обычные функции на Python, которые вы написали сами и которые она может позвать посреди ответа.
  • Tool / инструмент - функция с человеческим описанием. Когда её вызвать, модель решает по docstring, а что при этом произойдёт, решаете вы в теле функции. Никакой магии, всё честно.
  • Harness - «обвязка» вокруг модели: инструменты, правила безопасности, лимиты, подтверждения. Весь курс, по сути, про то, как собрать её своими руками.
  • Контекст - всё, что модель «помнит» в этом разговоре: ваши сообщения, её ответы, результаты инструментов. Места там не бесконечно, поэтому мы с самого начала ограничиваем, сколько строк возвращает read.

Быстрый путь

  1. Создайте проект и поставьте библиотеку pydantic-ai.
  2. Напишите main.py с агентом без инструментов - посмотрите на «догадки».
  3. Добавьте инструмент read: нумерация строк и потолок в 500 строк.
  4. Снова спросите про файл - теперь ответ должен опираться на реальное содержимое.

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

Файл Что делать
pyproject.toml Создать через uv init; добавить pydantic-ai через uv add.
main.py Создать. Сначала агент без tools, потом с инструментом read.

Подготовка проекта

Начинаем с пустой папки. uv run видит только то, что записано в проекте, так что пропустить шаг ниже не получится: интерпретатор честно ответит ModuleNotFoundError: No module named 'pydantic_ai' и никакого агента не будет.

Terminal

mkdir teensycode && cd teensycode
uv init --name teensycode
uv add pydantic-ai

Маленькая ловушка на будущее: в репозитории пакетов имя пишется через дефис (pydantic-ai), а в коде через подчёркивание (from pydantic_ai import Agent). Модель DeepSeek подключается одной строкой deepseek:deepseek-chat (подробнее в документации Pydantic AI).

Ключ API возьмите на platform.deepseek.com и положите в окружение:

export DEEPSEEK_API_KEY="sk-..."
ПРОВЕРКА Выполните uv run python -c "import pydantic_ai; print(pydantic_ai.__version__)". Должна появиться версия. Если снова ошибка импорта - вы не в папке с pyproject.toml или забыли uv add.

Упражнение 1.1

Сначала минимальный агент, потом один инструмент.

  • Импорты: Agent и (для инструмента) RunContext.
  • Модель: deepseek:deepseek-chat.
  • Инструмент read: путь к файлу, по желанию с какой строки начать (offset) и сколько строк взять (limit).
  • Не больше 500 строк за раз; в ответе инструмента у каждой строки номер.

Шаг 1. Чатбот (без инструментов)

Сначала соберём заведомо бесполезную версию: агент без единого инструмента. Это не потеря времени, а прививка - вы своими глазами увидите, как выглядит уверенная выдумка, и потом узнаете её в любом проекте. Напишите такой main.py:

main.py

import asyncio
import sys
from pathlib import Path

from pydantic_ai import Agent

cwd = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
prompt = " ".join(sys.argv[2:]) if len(sys.argv) > 2 else "Привет!"

agent = Agent(
    "deepseek:deepseek-chat",
    instructions=(
        f"Ты coding-агент.\nРабочая директория: {cwd}\n"
        "У тебя нет инструментов и нет доступа к файловой системе. "
        "Не выдумывай вызовы tools, XML, DSML или shell-команды. "
        "Отвечай только обычным текстом - можно честно сказать, "
        "что не видишь файлы, или предположить типичную структуру."
    ),
)

async def main() -> None:
    result = await agent.run(prompt)
    print(result.output)

if __name__ == "__main__":
    asyncio.run(main())

Terminal

uv run python main.py . "Какие файлы в этом проекте?"

Хороший исход - обычный текст: либо честное «файлы я не вижу», либо аккуратно придуманная структура проекта. Плохой исход - когда модель начинает изображать ls или сыпать странной разметкой, будто что-то выполняет. Выполнять ей нечем, так что это по-прежнему просто болтовня, и притворяться она может сколько угодно.

ЕСЛИ В ОТВЕТЕ ПОЯВИЛСЯ DSML / exec_command DeepSeek иногда рисует вызов команды текстом, даже когда инструментов нет. Это не выполнение на вашем компьютере - просто фантазия в result.output. Усильте instructions (как выше) или спросите мягче: «Что обычно лежит в pyproject.toml?». Когда появится настоящий @agent.tool, библиотека передаст модели список реальных инструментов, и вызовы пойдут через ваш Python-код.

Шаг 2. Один инструмент меняет всё

А теперь самое интересное. Замените main.py целиком, не дописывая куски к версии без tools: так проще, чем потом искать, где остался старый импорт. Кстати, импортов теперь два, Agent и RunContext.

RunContext - это «контекст запуска», через него инструмент добирается до того, что вы передали в deps=. У нас там лежит корневая папка проекта, и без deps=cwd функция просто не знает, от какого места отсчитывать пути.

main.py

import asyncio
import sys
from pathlib import Path

from pydantic_ai import Agent, RunContext

MAX_LINES = 500

cwd = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
prompt = " ".join(sys.argv[2:]) if len(sys.argv) > 2 else "Привет!"

agent = Agent(
    "deepseek:deepseek-chat",
    deps_type=Path,
    instructions=(
        f"Ты coding-агент.\nРабочая директория: {cwd}\n"
        "Используй инструмент read, чтобы открывать файлы. "
        "Не выдумывай содержимое и не имитируй tool-calls текстом."
    ),
)

@agent.tool
def read(
    ctx: RunContext[Path],
    path: str,
    offset: int | None = None,
    limit: int | None = None,
) -> str:
    """Прочитать файл проекта. Возвращает пронумерованные строки.
    WHEN TO USE: просмотр содержимого, конфигов, исходников.
    WHEN NOT TO USE: поиск по нескольким файлам (используй grep).
    """
    abs_path = (ctx.deps / path).resolve()
    if not str(abs_path).startswith(str(ctx.deps.resolve())):
        return "Ошибка: путь вне рабочей директории."
    if not abs_path.is_file():
        return f"Ошибка: файл не найден: {path}"

    lines = abs_path.read_text(encoding="utf-8").splitlines()
    start = (offset or 1) - 1
    lines = lines[start:]
    if limit is not None:
        lines = lines[:limit]

    truncated = len(lines) > MAX_LINES
    if truncated:
        lines = lines[:MAX_LINES]

    # Явная нумерация: каждая строка вида "12: содержимое"
    numbered_lines: list[str] = []
    first_line_no = offset or 1
    for i, line in enumerate(lines):
        numbered_lines.append(f"{first_line_no + i}: {line}")

    body = "\n".join(numbered_lines)
    if truncated:
        body += f"\n... (обрезано на {MAX_LINES} строках)"

    # Печатаем результат инструмента в консоль - иначе в ответе модели
    # будет только пересказ без номеров строк.
    print("--- tool read output (пронумерованные строки) ---")
    print(body)
    print("--- конец tool output ---")
    return body


async def main() -> None:
    result = await agent.run(prompt, deps=cwd)
    print("=== ответ модели ===")
    print(result.output)


if __name__ == "__main__":
    asyncio.run(main())
NameError: RunContext is not defined В импорте остался только Agent. Нужно: from pydantic_ai import Agent, RunContext.
ЗАЧЕМ ЛИМИТ 500 СТРОК Уберите его, попросите открыть лог на десять тысяч строк - и весь этот водопад осядет в разговоре до конца сессии, отъедая и место, и деньги на токены. Про контекст будет отдельный модуль, но привычку затыкать вывод лимитом проще завести сразу, с первого же инструмента.

Проверьте

Terminal

uv run python main.py . "Прочитай pyproject.toml"

Ожидаемый вид консоли (сначала инструмент, потом модель):

--- tool read output (пронумерованные строки) ---
1: [project]
2: name = "ai-loop-agent"
3: version = "0.1.0"
...
--- конец tool output ---
=== ответ модели ===
Вот содержимое файла pyproject.toml: ...

Если в консоли один пересказ и ни следа блока tool read output, значит в read потерялся print(body) из листинга. Сами номера строк в ответе модели никто не требует, они нужны в выводе инструмента. И пока у агента нет ни поиска, ни терминала, формулируйте просьбы прямо: «Прочитай вот этот файл».

Отдельно про пути, потому что тут легко получить неприятный сюрприз. Первый аргумент (. или полный путь к проекту) становится корнем: модель передаёт относительное имя вроде pyproject.toml, а код склеивает его с этим корнем и проверяет, что результат не вылез наружу. Попросите агента прочитать /etc/passwd - и вместо содержимого он должен вернуть скучное «путь вне рабочей директории». Если это так, значит все правильно.

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

  • Есть pyproject.toml, пакет ставится через uv add pydantic-ai
  • Без инструментов - обычный текстовый ответ, без реальных вызовов функций
  • С read - модель вызывает инструмент и опирается на содержимое файла
  • В консоли есть блок с строками 1: …, 2: …; в коде - offset, limit и потолок 500
  • Пути считаются от корня проекта; выход «наверх» или в /etc блокируется
ЭКСПЕРИМЕНТ Сделайте файл на 1000 строк: seq 1 1000 > /tmp/big.txt, попросите агента прочитать его (скопируйте файл в проект или укажите доступный путь). Уберите MAX_LINES и сравните. Что сломается раньше на длинной задаче - здравый смысл ответа или лимит контекста?