От чата к агенту
Попросите модель «посмотреть» ваш pyproject.toml, и она с самым
уверенным видом перечислит: имя проекта, версия, пара зависимостей.
Звучит правдоподобно, только файл она не открывала и открыть не может:
у неё нет ни рук, ни доступа к вашему диску, зато есть отличная память
на то, как такие файлы обычно выглядят. Это ещё не агент, это
вежливый угадыватель. Сегодня мы дадим ему один настоящий инструмент,
самую обычную Python-функцию чтения файла, и разница будет видна
с первого запуска: вместо «там обычно бывает» в ответе появятся
пронумерованные строки из вашего проекта.
read, реально читает файл с диска и отвечает
уже по фактам, а не по догадкам.
Слова, которые встретятся
- Чатбот - модель, которая умеет только говорить. Ни файлов, ни терминала, ни поиска: всё, что она выдаёт, собрано из прочитанного когда-то раньше.
- Агент - та же самая модель, но с руками. Руки - это инструменты (tools), обычные функции на Python, которые вы написали сами и которые она может позвать посреди ответа.
- Tool / инструмент - функция с человеческим описанием. Когда её вызвать, модель решает по docstring, а что при этом произойдёт, решаете вы в теле функции. Никакой магии, всё честно.
- Harness - «обвязка» вокруг модели: инструменты, правила безопасности, лимиты, подтверждения. Весь курс, по сути, про то, как собрать её своими руками.
-
Контекст - всё, что модель «помнит» в этом разговоре:
ваши сообщения, её ответы, результаты инструментов. Места там не
бесконечно, поэтому мы с самого начала ограничиваем, сколько строк
возвращает
read.
Быстрый путь
- Создайте проект и поставьте библиотеку
pydantic-ai. - Напишите
main.pyс агентом без инструментов - посмотрите на «догадки». - Добавьте инструмент
read: нумерация строк и потолок в 500 строк. - Снова спросите про файл - теперь ответ должен опираться на реальное содержимое.
Какие файлы трогаем
| Файл | Что делать |
|---|---|
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 или сыпать странной разметкой, будто
что-то выполняет. Выполнять ей нечем, так что это по-прежнему просто
болтовня, и притворяться она может сколько угодно.
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())
Agent. Нужно:
from pydantic_ai import Agent, RunContext.
Проверьте
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блокируется
seq 1 1000 > /tmp/big.txt, попросите агента прочитать его
(скопируйте файл в проект или укажите доступный путь). Уберите
MAX_LINES и сравните. Что сломается раньше на длинной задаче -
здравый смысл ответа или лимит контекста?