1. Настройка и первый успех

Добро пожаловать в путь по созданию ИИ-агентов (agent) на Python! К концу этой главы вы выполните свой первый успешный вызов большой языковой модели (Large Language Model, LLM) и поймёте, что именно происходило за кулисами. Это — фундамент для всего, что будет дальше.

Предварительные требования

Аудитория и предположения

Эта книга написана для Python-разработчиков, которые хотят создавать ИИ-агентов, но не имеют опыта работы с LLM или AI-фреймворками. Мы предполагаем, что вам комфортно с:

Основами Python: функции, классы, импорты, базовые структуры данных
Python 3.10+: у вас должен быть установлен Python версии 3.10 или выше
Виртуальными окружениями: созданием и активацией venv с python -m venv
Управлением пакетами: установкой пакетов через pip
Переменными окружения: установкой и чтением переменных окружения в вашей оболочке
API-ключами: пониманием того, что такое API-ключи и как получать их у поставщиков сервисов

Если какие-то из этих понятий вам незнакомы, рекомендуем отдельно повторить их перед продолжением. Документация Python и туториалы по виртуальным окружениям и pip — отличные отправные точки.

Чего мы НЕ предполагаем: вам не нужен бэкграунд в машинном обучении, нейросетях, трансформерах или теории ИИ. Мы будем объяснять специфичные для LLM понятия по мере их появления, всегда связывая их с привычными паттернами программирования.

Конвенция по модели

На протяжении этой книги мы будем использовать GPT-5-mini как модель по умолчанию в примерах. Вот почему:

Широко доступна: API OpenAI доступен по всему миру с простой регистрацией
Разумная скорость: при минимальном усилии рассуждения ответы приходят достаточно быстро для итеративной разработки
Экономична: при цене $0.25 за миллион входных токенов и $2.00 за миллион выходных токенов (по состоянию на 2026) она доступна для обучения и экспериментов
Достаточная функциональность: хорошо справляется с подавляющим большинством практических задач ИИ-агентов

Когда вы видите примеры кода без явно указанной модели, считайте, что мы используем GPT-5-mini. В главе 2 мы рассмотрим весь ландшафт доступных моделей (Claude, Gemini и другие варианты GPT) и обсудим, когда вы можете выбрать альтернативы в зависимости от размера контекстного окна, стоимости или специализированных возможностей.

1.1) Что такое LLM?

Прежде чем писать код, давайте определим, с чем именно мы работаем. Большая языковая модель (Large Language Model, LLM) — это нейронная сеть, обученная на огромных объёмах текстовых данных, чтобы предсказывать, какой текст должен идти следующим в последовательности.

Представьте это как чрезвычайно продвинутую систему автодополнения. Когда вы печатаете на телефоне, и он предлагает следующее слово — это простая версия того, что делают LLM. Но LLM работают в таком масштабе и с такой сложностью, что это позволяет им:

Генерировать связные, контекстно уместные ответы на вопросы
Писать код, эссе, письма и другой структурированный контент
Переводить между языками
Суммировать длинные документы
Извлекать информацию из неструктурированного текста
И многое другое

Чем LLM отличаются от традиционного ПО

Традиционное программное обеспечение следует явным правилам, которые вы программируете:

python

def calculate_discount(price, customer_type):
    if customer_type == "premium":
        return price * 0.8  # скидка 20%
    elif customer_type == "regular":
        return price * 0.95  # скидка 5%
    else:
        return price

Эта функция всегда выдаёт один и тот же результат для одних и тех же входных данных. Логика детерминирована и прозрачна.

LLM работают иначе. Вместо явных правил они используют паттерны, выученные из обучающих данных, чтобы генерировать ответы. Вы предоставляете входной текст (называемый промптом (prompt)), и модель генерирует выходной текст (называемый completion или response).

python

# Концептуальный пример — скоро мы напишем реальный код
response = llm.generate("Какую скидку стоит давать премиум-клиентам?")
# Пример вывода: "Премиум‑клиенты обычно получают скидки 15–25 %..."

У LLM нет «зашитого» процента скидки. Она генерирует ответ на основе паттернов, выученных при обучении. Это означает:

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

Ключевая терминология

Давайте определим термины, с которыми вы будете сталкиваться постоянно:

Промпт (prompt): входной текст, который вы отправляете модели. Думайте о нём как о «вопросе» или «инструкции»
Completion/Response: текст, который модель генерирует в ответ на ваш промпт
Токен (token): базовая единица, с которой работают LLM. Примерно 1 токен ≈ 4 символа или ¾ слова. "Hello world" — это около 2 токенов
Контекстное окно (context window): максимальный объём текста (в токенах), который модель может обработать за раз. У GPT-5-mini контекстное окно 400K токенов
Температура (temperature): параметр, управляющий случайностью. Ниже (0.0–0.3) = более сфокусировано и детерминированно. Выше (0.7–1.0) = более креативно и разнообразно

Что LLM умеют и чего не умеют

Понимание того, что LLM делают надёжно — и что они лишь кажется делают, — необходимо для создания устойчивых ИИ-агентов.

LLM отлично справляются с:

Пониманием и генерацией естественного языка: они могут распознавать намерение, генерировать связные ответы и обрабатывать сложные формулировки

"Я хочу возврат" → Распознаёт намерение: refund_request
"Суммируй этот документ" → Выдаёт краткое резюме

Следованием инструкциям в промптах: при чётких указаниях они могут выдавать структурированные результаты, например JSON или форматированный текст

"Преобразуй в JSON: John Smith, 32, lives in Boston"
→ {"name": "John Smith", "age": 32, "city": "Boston"}

Распознаванием паттернов в тексте: анализ тональности, категоризация и извлечение информации работают надёжно
Генерацией кода и структурированного контента: могут писать валидный Python, SQL или другой форматированный вывод при грамотном использовании промптов
Пошаговым рассуждением: когда явно попросить «думать пошагово», они методично разбивают задачи

Ограничения LLM:

Это не база данных: они не извлекают факты — они генерируют статистически правдоподобный текст. Они могут уверенно утверждать неверную информацию, которая звучит авторитетно.

"Когда вышел Python 4.0?" 
→ Может сгенерировать "Python 4.0 вышел в 2023" (ложь, но правдоподобно)

Это не калькулятор: они предсказывают, как должен выглядеть ответ, вместо вычисления. Простая арифметика часто работает; сложная математика непредсказуемо ломается.

"Сколько будет 8,247 × 6,839?" → Может выдать неверный результат, который выглядит разумно

Не детерминированы: один и тот же промпт может давать разные ответы каждый раз. Эта вариативность контролируется параметром temperature.
Не всегда точны: они генерируют правдоподобный текст независимо от фактической корректности. «Галлюцинации» — подробная, уверенная, но полностью выдуманная информация — встречаются часто.

Ключевая идея: стройте агентов, которые сочетают LLM (для понимания и принятия решений) с традиционными инструментами (для вычислений, получения данных и фактических операций). Мы реализуем этот паттерн, начиная с главы 13, где LLM решает, когда использовать калькулятор, вместо попыток считать самой.

Чему вы научитесь

В этой книге вы научитесь строить ИИ-агентов — системы, в которых LLM автономно решает, какие действия предпринимать для достижения целей, а не следует заранее заданной логике. Мы глубоко разберём эту парадигму в главе 2.

1.2) Установка зависимостей

Давайте настроим окружение разработки. Мы создадим чистую структуру проекта и установим LangChain — фреймворк, который будем использовать для создания ИИ-агентов.

Проверьте установку Python

Сначала убедитесь, что Python установлен в вашей системе. Мы рекомендуем Python 3.10 или выше (по состоянию на 2026, Python 3.13 или 3.14 — хорошие варианты).

Проверьте версию Python:

bash

python --version
# or
python3 --version

Вы должны увидеть вывод вроде Python 3.13.x или Python 3.14.x.

Если Python не установлен:

macOS:
- Скачайте с python.org
- Или используйте Homebrew: brew install python@3.14
Windows:
- Скачайте с python.org
- Во время установки отметьте "Add Python to PATH"
Linux:
- Ubuntu/Debian: sudo apt update && sudo apt install python3.14
- Fedora: sudo dnf install python3.14

После установки проверьте ещё раз с python --version.

Примечание: на некоторых системах вам может понадобиться использовать python3 вместо python. На протяжении этой книги, если python не работает, попробуйте python3.

Создайте свой проект

Откройте терминал и создайте новую директорию для проекта:

bash

mkdir agentic-ai-project
cd agentic-ai-project

Создайте виртуальное окружение, чтобы изолировать зависимости:

bash

python -m venv venv

Активируйте виртуальное окружение:

bash

# On macOS/Linux:
source venv/bin/activate
 
# On Windows:
venv\Scripts\activate

В приглашении терминала должно появиться (venv), что означает, что виртуальное окружение активно.

Установите LangChain и OpenAI

Мы установим интеграцию LangChain с OpenAI, которая включает всё необходимое для работы с моделями OpenAI:

bash

pip install langchain-openai

Это установит langchain-openai вместе с зависимостями, включая langchain-core (базовые абстракции LangChain) и Python-клиент OpenAI. Вы должны увидеть вывод, подтверждающий установку нескольких пакетов.

Проверьте установку:

bash

pip show langchain-openai

Вы должны увидеть сведения об установленном пакете, включая номер версии и расположение. Это подтверждает, что установка прошла успешно.

Получите ваш OpenAI API Key

Чтобы вызывать модели OpenAI, вам нужен API-ключ:

Перейдите на platform.openai.com
Зарегистрируйтесь или войдите
Откройте раздел API Keys в настройках аккаунта
Нажмите "Create new secret key"
Скопируйте ключ (он начинается с sk-)

⚠️ Предупреждение по безопасности: обращайтесь с этим ключом как с паролем. Никогда не коммитьте его в систему контроля версий и не публикуйте. Любой, у кого есть ваш ключ, может делать API-вызовы, которые будут выставлены на ваш аккаунт.

Задайте API-ключ через переменную окружения

Рекомендуемый способ передать API-ключ — через переменную окружения:

bash

# On macOS/Linux:
export OPENAI_API_KEY='sk-your-actual-key-here'
 
# On Windows (Command Prompt):
set OPENAI_API_KEY=sk-your-actual-key-here
 
# On Windows (PowerShell):
$env:OPENAI_API_KEY='sk-your-actual-key-here'

Примечание: это значение временное и пропадёт при закрытии терминала. Для постоянного решения вы можете либо:

Добавить команду export в конфигурационный файл вашей оболочки (.bashrc, .zshrc и т. д.)
Использовать файл .env (мы настроим это в главе 3 для лучшей организации проекта)

Пока что временной настройки достаточно, чтобы продолжить.

Проверьте, что переменная задана:

bash

# On macOS/Linux:
echo $OPENAI_API_KEY
 
# On Windows (Command Prompt):
echo %OPENAI_API_KEY%
 
# On Windows (PowerShell):
echo $env:OPENAI_API_KEY

Вы должны увидеть напечатанный API-ключ. Если нет — повторите команду export/set и убедитесь, что нет опечаток.

1.3) Ваш первый вызов LLM

Теперь самое интересное — сделаем ваш первый вызов LLM. Создайте файл first_call.py:

python

# first_call.py
from langchain_openai import ChatOpenAI
 
# Инициализируем LLM
llm = ChatOpenAI(model="gpt-5-mini")
 
# Отправляем промпт и получаем ответ
response = llm.invoke("What is LangChain?")
 
# Печатаем ответ
print(response.content)

Запустите:

bash

python first_call.py

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

LangChain is a framework designed to simplify the development of applications powered by large language models (LLMs). It provides tools and abstractions for building chains of LLM calls, integrating external data sources, managing prompts, and creating agents that can interact with various APIs and databases. LangChain makes it easier to build complex AI applications by providing reusable components and patterns.

Поздравляем! Вы только что сделали свой первый вызов LLM. Давайте разберём, что произошло в этом коде.

Устранение неполадок: если вы видите ошибку:

AuthenticationError: API-ключ неверный или не задан → проверьте переменную окружения OPENAI_API_KEY (см. раздел 1.2)
RateLimitError: запросы слишком частые или превышен лимит использования → подождите несколько секунд и повторите, или проверьте использование на platform.openai.com/usage
APIConnectionError: проблема с подключением к сети → проверьте подключение к интернету

Понимание кода

Импортируйте обёртку LLM:

python

from langchain_openai import ChatOpenAI

ChatOpenAI — это обёртка LangChain вокруг чат-моделей OpenAI. Она берёт на себя аутентификацию API, форматирование запросов и парсинг ответов.

Инициализируйте модель:

python

llm = ChatOpenAI(model="gpt-5-mini")

Это создаёт экземпляр, настроенный на использование GPT-5-mini. За кулисами LangChain читает переменную окружения OPENAI_API_KEY для аутентификации. Вы также могли бы передать ключ явно:

python

llm = ChatOpenAI(model="gpt-5-mini", api_key="sk-your-key")

Но использование переменных окружения безопаснее и гибче.

Вызовите модель:

python

response = llm.invoke("What is LangChain?")

Метод invoke() отправляет ваш промпт в API OpenAI и ждёт полного ответа. Это синхронный вызов — ваша программа ставится на паузу до тех пор, пока ответ не придёт.

Доступ к содержимому ответа:

python

print(response.content)

Объект ответа содержит несколько полей. Поле .content содержит фактический текст, сгенерированный моделью. Другие поля мы рассмотрим в следующем разделе.

Попробуйте разные промпты

Измените промпт, чтобы увидеть, как модель реагирует на разные входные данные:

python

# first_call.py
from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
 
# Попробуйте разные промпты
prompts = [
    "Explain Python decorators in one sentence.",
    "What's 15 * 23?",
    "List three benefits of using type hints in Python.",
]
 
for prompt in prompts:
    response = llm.invoke(prompt)
    print(f"Prompt: {prompt}")
    print(f"Response: {response.content}\n")

Модель справляется с разными типами запросов — объяснениями, вычислениями и структурированными списками. Вы заметите, что ответы могут немного различаться, если запускать один и тот же промпт несколько раз. Это нормальное поведение — мы разберём, почему так происходит и как это контролировать, в главе 2.

1.4) Что только что произошло? (Поток «запрос → модель → ответ»)

Давайте рассмотрим, что именно произошло, когда вы вызвали llm.invoke(). Понимание этого потока критически важно для создания надёжных ИИ-агентов.

Полный цикл «запрос-ответ»

Давайте пройдём каждый шаг:

Шаг 1: Ваш код вызывает invoke()

python

response = llm.invoke("What is LangChain?")

Метод invoke() — это ваш основной интерфейс к LLM. Вы передаёте строку промпта, и он возвращает объект ответа, содержащий ответ модели. За этим простым вызовом автоматически происходит несколько шагов.

Шаг 2: LangChain форматирует запрос

LangChain преобразует вашу строку в структурированный API-запрос. За кулисами он создаёт JSON-пейлоад примерно такого вида:

json

{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is LangChain?"
    }
  ],
  "temperature": 1.0
}

Массив messages — это то, как чат-модели получают входные данные. У каждого сообщения есть role (user, assistant или system) и content (текст). Роли сообщений мы разберём в главе 4.

Шаг 3: API-вызов к OpenAI

LangChain отправляет HTTPS POST-запрос на endpoint API OpenAI:

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json
 
{request payload}

Ваш API-ключ аутентифицирует запрос. Серверы OpenAI получают запрос и маршрутизируют его к указанной модели.

Шаг 4: Модель обрабатывает промпт

GPT-5-mini получает ваш промпт и генерирует ответ токен за токеном. Модель:

Преобразует ваш текст в токены (числовые представления)
Пропускает токены через слои нейросети
Предсказывает наиболее вероятный следующий токен
Повторяет, пока не сгенерирует полный ответ или не достигнет условия остановки

Это происходит на серверах OpenAI — ваш код просто ждёт результат.

Шаг 5: API возвращает ответ

API OpenAI отправляет обратно JSON-ответ:

json

{
  "id": "chatcmpl-8x7y9z",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LangChain is a framework designed to simplify..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 58,
    "total_tokens": 70
  }
}

Ключевые поля:

message.content: сгенерированный текст
usage: количество токенов для биллинга и мониторинга
finish_reason: почему генерация остановилась ("stop" = естественное завершение, "length" = достигнут лимит токенов)

Шаг 6: LangChain парсит ответ

LangChain преобразует JSON в Python-объект, с которым можно работать:

python

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("What is LangChain?")
 
# Изучаем объект ответа
print(f"Content: {response.content}")
print(f"Type: {type(response)}")
print(f"Response metadata: {response.response_metadata}")

Вывод:

Content: LangChain is a framework designed to simplify...
Type: <class 'langchain_core.messages.ai.AIMessage'>
Response metadata: {'token_usage': {'completion_tokens': 58, 'prompt_tokens': 12, 'total_tokens': 70}, 'model_name': 'gpt-5-mini', 'finish_reason': 'stop'}

Ответ — это объект AIMessage с несколькими полезными атрибутами:

content: сгенерированный текст (то, что обычно нужно)
response_metadata: использование токенов, имя модели, причина остановки
id: уникальный идентификатор этого ответа
usage_metadata: подробная разбивка по токенам

Понимание использования токенов

Прежде чем смотреть на счётчики токенов, короткое замечание: токены — базовые единицы, которые обрабатывают LLM. В английском тексте обычно получается чуть больше 1 токена на слово (например, "explain quantum computing" = 3 слова, 4–5 токенов), но для неанглийских языков, таких как корейский или китайский, требуется значительно больше токенов, чтобы представить тот же текст. Мы разберём токены подробнее в главе 2.

Давайте рассмотрим потребление токенов более внимательно:

python

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("Explain quantum computing in simple terms.")
 
usage = response.response_metadata['token_usage']
print(f"Input tokens: {usage['prompt_tokens']}")
print(f"Output tokens: {usage['completion_tokens']}")
print(f"Total tokens: {usage['total_tokens']}")

Вывод:

Input tokens: 11
Output tokens: 95
Total tokens: 106

Примечание: prompt_tokens = входные токены (ваш промпт), completion_tokens = выходные токены (ответ модели), total_tokens = сумма обоих.

Потребление токенов меняется в зависимости от:

Длины промпта: более длинные промпты используют больше входных токенов
Детализации ответа: подробные ответы генерируют больше выходных токенов
Сложности языка: технические термины и код могут токенизироваться иначе

Например, короткий промпт вроде "What's 2+2?" может использовать всего 5–6 входных токенов и 8–10 выходных, а "Write a detailed essay about the history of Python programming language" может использовать 15–20 входных токенов и 500+ выходных токенов.

Расчёт стоимости для примера выше:

При ценах GPT-5-mini ($0.25 за миллион входных токенов, $2.00 за миллион выходных токенов):

Вход: 11 токенов × $0.25 / 1,000,000 = $0.00000275
Выход: 95 токенов × $2.00 / 1,000,000 = $0.00019
Итого: ~$0.0002 (две сотых цента)

Вы платите и за входные, и за выходные токены, но выходные токены стоят дороже (в этом случае в 8×).

Что вы узнали

Теперь вы понимаете полный жизненный цикл вызова LLM:

Ваш код предоставляет строку промпта
LangChain форматирует её в API-запрос с аутентификацией
API OpenAI маршрутизирует запрос к модели
Модель генерирует ответ токен за токеном
API возвращает структурированный JSON с ответом и метаданными
LangChain парсит его в Python-объект
Ваш код получает доступ к содержимому и метаданным

Вы также узнали:

Как исследовать объекты ответов и извлекать метаданные
Как использование токенов влияет на стоимость

Этот фундамент подготовит вас к главе 2, где мы разберём, как LLM устроены «под капотом», сравним разные модели и изучим техники prompt engineering, чтобы получать лучшие результаты.