Окружение: Python, VS Code и «мозг» для агента

Прежде чем агента собирать, ему нужно приготовить место: интерпретатор, редактор и — главное — «мозг», к которому ваш код будет ходить по HTTP. Занятие скучное ровно настолько, насколько скучным бывает фундамент: сделаете один раз — больше к этому не вернётесь.

Python и виртуальное окружение

Курс рассчитан на Python 3.12 или новее. Проверьте:

bash

python --version

Если видите 3.12–3.14 — порядок. Проект изолируем виртуальным окружением, чтобы пакеты курса не смешивались с системными:

bash

python -m venv .venv

# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# macOS и Linux:
source .venv/bin/activate

После активации в начале строки приглашения появится (.venv). Если пользуетесь uv — отлично, uv venv тоже подойдёт: курсу важно наличие окружения, а не инструмент.

Ставим два пакета, с которыми будем работать весь курс:

bash

pip install openai pytest

openai — клиентская библиотека OpenAI-совместимого API (не пугайтесь имени: через него ходят и к другим провайдерам, об этом ниже). pytest — стандартный раннер тестов в питоне; если не писали тесты — не страшно, в домашнихках тесты даются готовыми, ваша задача — сделать их зелёными.

Редактор

VS Code с расширением Python — достаточно: подсветка, запуск, дебаг. PyCharm тоже подходит — выбирайте привычное. Специальных инструментов для «AI-разработки» не нужно: агент — обычный питоновский проект.

Мозг: откуда модель будет отвечать

Ваш код будет говорить с моделью по одному протоколу — OpenAI-совместимому API. Его понимают десятки провайдеров, поэтому вы не привязаны к одному вендору: смена «мозга» — это другая переменная окружения, а не переписывание кода. Три рабочих варианта:

OpenRouter — агрегатор моделей под одним API. Заходите на openrouter.ai, регистрируетесь, создаёте ключ. У части моделей в списке есть пометка «free» — они не тарифицируются; для обучения этого достаточно. Адрес API: https://openrouter.ai/api/v1.

Ollama — модель работает на вашей машине, без ключей и без интернета. Устанавливаете с ollama.com, скачиваете модель (ollama pull ...; ориентируйтесь на модели примерно 7–9 миллиардов параметров — они комфортно живут на ноутбуке с 16 ГБ оперативной памяти), и обращаетесь к http://localhost:11434/v1. Для русской аудитории это самый предсказуемый путь: ничего не блокируется, ничего не платится. Плата — скорость и скромное качество против облачных моделей.

FakeLLM — не модель, а заглушка: класс с тем же методом ask, возвращающий заготовку. Все домашки курса проходят с ней без сети и ключей; там, где хочется «живого» ответа, переключаетесь на настоящее API. С FakeLLM познакомитесь уже в домашке этого модуля.

Ключи: сразу правильно

Самая дорогая привычка, которую можно приобрести в первый день, — вписать API-ключ в код. Такой файл имеет свойство доезжать до GitHub, а ключи сканируются ботами быстрее, чем вы успеваете нажать force push. Ключ живёт в переменной окружения, точка:

bash

# Git Bash / macOS / Linux:
export LLM_API_KEY="ваш-ключ"

# PowerShell:
$env:LLM_API_KEY = "ваш-ключ"

Переменная живёт в текущей сессии терминала. Задали ключ в одном окне, а запустили код в другом — программа ключа не увидит; это ловит почти каждого на первой неделе, теперь вы предупреждены. Для постоянства переменную добавляют в профиль оболочки или в .env-файл — до этого дойдём в модуле про CI, пока достаточно экспорта.

Первый запрос из кода

Создайте в devbuddy файл llm.py — это обёртка над API, которую мы будем наращивать весь курс:

python

# llm.py
import os

from openai import OpenAI


class LLMClient:
    """Обёртка над OpenAI-совместимым API.

    Провайдер меняется переменными окружения, код не меняется:
    OpenRouter, Ollama и другие понимают один и тот же протокол.
    """

    def __init__(self) -> None:
        if not os.environ.get("LLM_MODEL"):
            raise ValueError("Задайте LLM_MODEL — имя модели в переменных окружения")

        self.client = OpenAI(
            base_url=os.environ.get("LLM_BASE_URL", "https://openrouter.ai/api/v1"),
            api_key=os.environ.get("LLM_API_KEY", ""),
        )
        self.model = os.environ["LLM_MODEL"]

    def ask(self, prompt: str) -> str:
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
        )
        return response.choices[0].message.content

И hello.py, который её использует:

python

# hello.py
from llm import LLMClient


def main() -> None:
    llm = LLMClient()
    answer = llm.ask("Ответь одним словом: работает?")
    print("Ответ модели:", answer)


if __name__ == "__main__":
    main()

Запуск с Ollama выглядит так (для OpenRouter LLM_BASE_URL можно не задавать — он адрес по умолчанию, а имя модели возьмите из списка провайдера):

bash

export LLM_BASE_URL=http://localhost:11434/v1
export LLM_API_KEY=ollama          # локальной Ollama ключ не нужен, но поле не бывает пустым
export LLM_MODEL=имя-модели       # то, что вы скачивали через ollama pull
python hello.py

java

Ответ модели: Да

Что здесь происходит: клиент собирает HTTP-запрос с вашим промптом, отправляет на base_url с ключом в заголовке, получает обратно ответ модели. Проверка в __init__ — принцип «падай сразу»: ошибку «не задана модель» лучше увидеть при старте с понятным текстом, чем в глубине HTTP-вызова.

Если вместо «Да» пришла ошибка, типовые причины такие. 401 — ключ не задан или неверен (или задан не в той сессии терминала). connection refused — Ollama не запущена или неверный base_url (не забудьте суффикс /v1). model not found — опечатка в LLM_MODEL.

Что запомнить

• Python 3.12+, venv, пакеты openai и pytest — фундамент, который больше не будет меняться.

• «Мозг» подключается через OpenAI-совместимый API: OpenRouter, локальная Ollama или FakeLLM в тестах. Смена провайдера — переменные окружения, не код.

• Ключ — только в переменную окружения. Файл с ключом в git — инцидент, а не мелочь.

• LLMClient.ask() — единственный метод, пока нужный агенту: промпт на вход, текст на выход. Дальше курс будет его усложнять.