BlackboxBook/book/23_getting_started.md

ГЛАВА 23. КАК НАЧАТЬ: ОТ ПЕРВОГО ПРОМПТА ДО РАБОЧЕГО АГЕНТНОГО КОНТУРА

---

Внедрение LLM в рабочий процесс похоже на обучение вождению. Есть соблазн сразу выехать на автобан — запустить полностью автономного агента, который будет писать код, деплоить и общаться с клиентами. Но любой инструктор скажет: сначала площадка, потом тихие улицы, потом город, и только потом — автобан. В этой главе мы пройдём этот путь: от первого промпта в ChatGPT до production-контура, обрабатывающего тысячи задач в день.

Хорошая новость: к апрелю 2026 года барьер входа радикально снизился. У инженера есть выбор между hosted API и open-weight self-hosted моделями, а запуск прототипа больше не требует отдельной R&D-команды. Это значит: экспериментировать стало проще, а переход к production можно строить постепенно — через eval-наборы, верификацию и ограниченные контуры.

---

23.1. Где агентный подход уже выгоден

Матрица применимости

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

1. Структурированность — насколько чётко задача описывается правилами
2. Измеримость — есть ли объективные критерии качества результата
3. Повторяемость — как часто задача выполняется

Задача	Структурированность	Измеримость	Повторяемость	Рекомендация
Код-ревью по стандартам	Высокая	Высокая (правила)	Высокая	Агент
Обработка документов (парсинг, extraction)	Высокая	Высокая (точность)	Высокая	Агент
Генерация тестов и фикстур	Высокая	Высокая (pass rate)	Высокая	Агент
Рефакторинг по паттернам	Средняя	Средняя (тесты)	Средняя	Агент
Аналитика с SQL/API	Высокая	Высокая (данные)	Средняя	Агент + инструменты
Перевод технической документации	Средняя	Средняя (BLEU/human)	Средняя	Ассистент
Творческий копирайтинг без брифа	Низкая	Низкая (субъективно)	Низкая	Человек
Стратегические решения	Низкая	Низкая	Низкая	Человек

Где LLM-агенты уже работают в production (2025–2026)

1. Код-ревью и автоматический рефакторинг:

• GitHub Copilot, Cursor, Windsurf — IDE-интегрированные агенты
• CodeRabbit, Ellipsis — автоматический ревью pull requests
• SWE-bench Verified — важный бенчмарк для coding-агентов, но сравнивать результаты нужно только внутри одного harness/version
• Практический сигнал: агентное ревью окупается там, где замечания можно проверять тестами, линтерами и policy-check'ами

2. Обработка документов:

• Extraction из PDF/DOCX/сканов → структурированные данные
• Классификация обращений, маршрутизация в support
• Практический сигнал: это один из лучших стартовых use case, потому что поля, шаблоны и выходной формат легко проверять программно

3. Тестирование:

• Генерация unit-тестов по контрактам (Diffblue, CodiumAI/Qodo)
• Генерация тестовых данных и фикстур
• Практический сигнал: генерация тестов окупается только если тесты автоматически прогоняются и отбраковываются при падении

4. Data engineering:

• Генерация SQL-запросов по natural language (Text2SQL)
• ETL-пайплайны с валидацией
• Практический сигнал: Text2SQL работает лучше всего там, где есть schema grounding, read-only доступ и проверка результата через БД

Где НЕ стоит начинать

• Нулевые метрики: если нет способа автоматически проверить результат → верификация дороже генерации
• Высокая неопределённость: задача меняется каждый раз → нет стабильного протокола
• Regulatory без human-in-the-loop: медицина, финансовый compliance, юридические решения — LLM как ассистент, не автономный агент

---

23.2. Выбор модели: дерево решений

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

                        ┌─ Задача требует рассуждений,
                        │  длинного контекста, сложной
                        │  генерации кода?
                        │
                   ДА ──┤                    НЕТ ──┐
                        │                          │
                        ▼                          ▼
            Frontier-модель:              Задача требует
            Claude Sonnet/Opus 4.6,       скорости и дешевизны?
            GPT-5.4, Gemini 3.x           (классификация, extraction,
                        │                рутинная генерация)
                        │                     │
                        │              ДА ────┤──── НЕТ
                        │                     │        │
                        │                     ▼        ▼
                        │              Mini-модель:  Средний tier:
                        │              GPT-5.4-mini,  Claude Sonnet 4.6,
                        │              Claude Haiku 4.5, GPT-5.4
                        │              Gemini Flash
                        │
                        ▼
           Данные не могут покидать
           периметр компании?
                   │          │
              ДА ──┘          └── НЕТ
                   │                │
                   ▼                ▼
           Self-hosted:        Cloud API
           Llama 4 Scout/      (самый быстрый
           Maverick,           старт)
           Qwen3/3.5,
           DeepSeek-V3
           через vLLM/Ollama

Практические рекомендации

Сценарий	Рекомендуемое семейство	Что важно проверить
Прототипирование, эксперименты	GPT-5.4-mini, Claude Haiku 4.5	Цена, latency, JSON/tool use
Production: классификация, extraction	Mini/Flash-модели, Llama 4 Scout (self-hosted)	Accuracy на вашем eval-наборе
Production: код, рассуждения	Claude Sonnet/Opus 4.6, GPT-5.4 (reasoning_effort=high)	Тесты, long-context, tool reliability
Production: агентные контуры (Planner)	Claude Sonnet 4.6, GPT-5.4, Gemini 3.x	Качество планов и verifier-loop
Приватность, self-hosted	Llama 4, Qwen3/3.5, DeepSeek-V3	GPU budget, latency, ops complexity
Быстрый прототип self-hosted	Llama 4 Scout, Qwen3/3.5 подходящего размера через Ollama	Реальная пропускная способность на вашем железе
Edge / on-device, privacy	Gemma 4 E2B/E4B, Phi-4-mini, Qwen3.5-0.8B	Реальная latency на целевом устройстве, качество на вашем eval

Правило: начинайте с самой дешёвой модели, которая проходит ваш eval-набор с accuracy > 85%. Upgrade только когда дешёвая модель не справляется.

SLM как стартовая точка. В 2026 году SLM (Phi-4-mini, Gemma 4 E2B/E4B, SmolLM3-3B) стали жизнеспособной стартовой моделью для classification, extraction и простой генерации. Если задача не требует сложного рассуждения или длинного контекста — начните с SLM и переходите к frontier только при провале на eval-наборе. Это не компромисс, а правило наименьшего достаточного ресурса.

---

23.3. Инфраструктура: API, self-hosted или гибрид

Вариант 1: Cloud API (быстрый старт)

Когда выбирать: прототип, малый объём запросов (< 100K/день), нет требований к приватности данных.

Провайдер	Преимущества	Ограничения
OpenAI API	Сильная агентная экосистема, structured outputs, MCP/connectors	Vendor lock-in, данные уходят в облако
Anthropic API	Сильные coding/agent workflows, prompt caching, длинный контекст	Меньше модельных tier'ов
Google Vertex AI / Gemini API	Gemini 3.x и 2.5, мультимодальность	Сложнее матрица продуктов и настроек
Together/Fireworks/Groq	Дешёвый inference опенсорсных моделей	Меньше гарантий SLA

Стоимость: $50–500/мес для типичного стартапа, оплата по факту.

Вариант 2: Self-hosted (контроль и приватность)

Когда выбирать: данные не могут покидать периметр, высокий объём запросов (> 500K/день), нужна предсказуемая стоимость.

Стек 2026 года:

• vLLM — production-grade inference server, поддержка PagedAttention, continuous batching, tensor parallelism. Стандарт индустрии. OpenAI-совместимый API.
• llm-d — Kubernetes-native distributed inference, автомасштабирование, prefix caching. Для enterprise-уровня.
• Ollama — для локальной разработки и прототипирования. Один бинарник, ollama run llama4-scout — и модель работает.
• Модели: Llama 4 Scout, Llama 4 Maverick, Qwen3/3.5, DeepSeek-V3, GLM-5.1, Gemma 4. Конкретный выбор определяется не пресс-релизом, а вашим latency/cost/SLA-профилем.

Стоимость: от $2000/мес за 1 GPU-сервер (A100/H100) до $50K+ для кластера.

Вариант 3: Гибрид (реальность большинства компаний)

Паттерн: cloud API для экспериментов и непредсказуемых нагрузок, self-hosted или edge для production с предсказуемым трафиком.

┌────────────────────────────────────────────────────────────┐
│                  ГИБРИДНАЯ АРХИТЕКТУРА                      │
│                                                            │
│  ┌──────────────┐    ┌──────────────────────────────────┐  │
│  │  Разработка   │    │        Production                │  │
│  │              │    │                                  │  │
│  │  Cloud API   │    │  ┌─────────┐   ┌──────────────┐ │  │
│  │  (OpenAI,    │    │  │ vLLM /  │   │ Cloud API    │ │  │
│  │  Anthropic)  │    │  │ llm-d   │   │ (fallback)   │ │  │
│  │              │    │  │ Llama 4 │   │              │ │  │
│  │  Быстрые     │    │  │ Qwen3/  │   │ Frontier     │ │  │
│  │  эксперименты│    │  │ 3.5     │   │ модели для   │ │  │
│  │  A/B-тесты   │    │  │ Рутина, │   │ сложных      │ │  │
│  │              │    │  │ bulk    │   │ кейсов       │ │  │
│  └──────────────┘    │  └─────────┘   └──────────────┘ │  │
│                      └──────────────────────────────────┘  │
│                                                            │
│  Роутер: простые задачи → self-hosted,                     │
│          сложные/edge cases → cloud frontier               │
└────────────────────────────────────────────────────────────┘

Тренд 2026: гибридный подход встречается всё чаще. Рутинные запросы удобно отдавать дешёвой self-hosted или mini-модели, а сложные edge-cases — frontier API. Точные проценты маршрутизации зависят от продукта и eval-набора, поэтому не копируйте чужие числа без своих замеров.

---

23.4. Минимальный агентный контур

Если вы уже прочитали о моделях и инфраструктуре выше, самое время посмотреть, как выглядит минимальный контур в коде. Ниже — компоненты, которые можно собрать за пару дней.

Архитектура: 4 компонента

┌─────────────────────────────────────────────────────┐
│                    АГЕНТНЫЙ КОНТУР                    │
│                                                       │
│   Input ──► [Planner] ──► [Executor + Tools] ──►     │
│                                │                      │
│                                ▼                      │
│                          [Verifier]                   │
│                           │      │                    │
│                      pass ▼      ▼ fail               │
│                       Output   Loop back              │
│                               (к Planner)             │
└─────────────────────────────────────────────────────┘

Компоненты контура

Четыре компонента, каждый со строго определённым контрактом:

Компонент 1: Planner (Планировщик) — декомпозирует входной запрос на план из атомарных шагов. Каждый шаг (Step) содержит: id, description, tool (инструмент для выполнения или null), input_data, output_data, status (pending → in_progress → completed / failed). Промпт планировщика использует XML-разметку: <role>, <rules>, <available_tools>, <task>. Ответ — в JSON: {"goal": "...", "steps": [{"id": 1, "description": "...", "tool": "...", "input_data": {}}]}. Ограничение: максимум N шагов (конфигурируемый параметр).

Компонент 2: Executor (Исполнитель) — выполняет каждый шаг. Если шаг требует инструмента — делегирует зарегистрированному Tool (протокол: name, description, execute(**kwargs) -> dict). Если инструмент не нужен — формирует промпт с контекстом предыдущих шагов и вызывает LLM. Обработка ошибок: exception → шаг получает статус FAILED, ошибка записывается в output_data.

Компонент 3: Verifier (Верификатор) — проверяет результат каждого шага. Два режима: (1) программная проверка (SQL-результат: error, пустой результат; код: exit code), (2) LLM-верификация как fallback — модель оценивает, выполнен ли шаг корректно, и возвращает {passed, confidence, issues, suggestion}. Архитектура агентного контура и принципы верификации подробно описаны в Главе 10.

Компонент 4: Orchestrator (Оркестратор) — управляет циклом Plan → Execute → Verify → Loop/Output. На каждой итерации проходит по шагам плана, для каждого вызывает Executor, затем Verifier. Если верификация не прошла — шаг возвращается в PENDING с feedback (issues + suggestion), контур переходит к новой итерации. Если все шаги прошли — возвращает результат. max_iterations — защита от зацикливания (по умолчанию 5). При исчерпании итераций возвращает частичный результат.

Промпт для генерации агентного контура: Напиши на Python минимальный агентный контур из 4 компонентов: (1) Planner — dataclass Step (id, description, tool, input_data, output_data, status) и Plan (goal, steps, max_iterations), промпт с XML-разметкой; (2) Executor — принимает dict[str, Tool] (Protocol: name, description, execute), для каждого шага вызывает tool или LLM; (3) Verifier — программная проверка (SQL, code) + LLM-fallback, возвращает VerificationResult(passed, confidence, issues, suggestion); (4) AgentLoop — цикл plan→execute→verify с max_iterations, перепланирование при fail. Стек: OpenAI SDK или Anthropic SDK. Логирование каждого шага через logging. Type hints, dataclasses, Protocol для Tool.

Практический стартовый skeleton репозитория

Если делать прикладной контур, а не абстрактную демо-схему, полезно сразу разложить код по папкам:

agent_app/
  prompts/
    planner.xml
    verifier.xml
  tools/
    sql_tool.py
    code_exec.py
    search_tool.py
  agent/
    models.py
    planner.py
    executor.py
    verifier.py
    loop.py
  evals/
    golden.jsonl
  tests/
    test_verifier.py
    test_tools.py

Что здесь важно:

• prompts/ версионируются отдельно от Python-кода;
• tools/ скрывают интеграции и дают единый интерфейс execute(**kwargs);
• agent/ содержит orchestration logic без прямой привязки к конкретному бизнес-домену;
• evals/golden.jsonl появляется с первого дня, а не после первого инцидента.

Это уже достаточно хороший минимальный старт для реального use case вроде «генерация SQL + верификация», «агент по документации» или «code review assistant». Не пытайтесь начать с 20 агентов и memory graph. Сначала нужен маленький контур, который можно прогнать end-to-end, измерить и отладить.

Что логировать (LDD — Log-Driven Development)

Каждый вызов LLM записывается как структурированная запись (log entry) с полями: timestamp, iteration, component (planner / executor / verifier), step_id, action, input_summary (краткое описание входа, не полный промпт), output_summary, tokens_used, latency_ms, verification_passed, error.

Это позволяет:

• Отладку: найти, где именно контур ошибся
• Оптимизацию: какой шаг тратит больше всего токенов
• Мониторинг: алерты на рост error rate, латентности, стоимости

---

23.5. Как вводить ИИ постепенно

Внедрение LLM в команде — это обучение вождению. Нельзя сесть за руль и сразу выехать на МКАД. Есть четыре уровня, и каждый нужно пройти.

Уровень 0: Инструктор за рулём — вы наблюдаете

Аналогия: вы сидите на пассажирском сиденье. Инструктор (LLM) показывает, как ехать, но все решения — ваши.

Человек → вопрос → LLM → ответ → Человек проверяет → Результат

Характеристики:

• Человек принимает все решения
• LLM = черновик, который человек редактирует
• Нет автоматизации, нет инструментов
• Риски минимальны

Когда переходить дальше: когда > 70% ответов LLM принимаются без изменений.

Примеры:

• ChatGPT/Claude для написания черновиков писем
• Copilot для автодополнения кода (с ревью разработчиком)
• Генерация SQL-запросов с ручной проверкой перед execution

Что попробовать прямо сейчас: откройте Claude или ChatGPT, вставьте кусок своего кода и попросите написать для него docstring. Оцените: сколько из 10 результатов вы примете без правок?

Уровень 1: Вы за рулём, инструктор рядом

Аналогия: вы держите руль, но инструктор (человек-ревьюер) сидит рядом и может нажать на тормоз. Едете по знакомым тихим улицам — рутинные задачи.

Input → [LLM + правила] → автоматическое действие (для рутинных кейсов)
                         → human review (для edge cases)

Характеристики:

• LLM выполняет повторяемые задачи автоматически
• Правила определяют, когда нужен человек
• Инструменты подключены, но ограничены (read-only)

Когда переходить дальше: когда error rate на автоматизированных задачах < 5%.

Примеры:

• Автоклассификация тикетов (confidence > 0.9 → автоматически, < 0.9 → человеку)
• Автоматический перевод документации с post-editing
• Генерация unit-тестов → запуск → если pass → коммит

Уровень 2: Самостоятельная езда по знакомым дорогам

Аналогия: вы водите сами, но по маршрутам, которые хорошо знаете. GPS (верификатор) подсказывает, если вы свернули не туда. На незнакомых перекрёстках — останавливаетесь и звоните другу (human fallback).

Input → [Planner] → [Executor + Tools] → [Verifier] → Output
                                              ↓ fail
                                         [Re-plan / Human]

Характеристики:

• Полный агентный контур с верификацией
• Инструменты имеют write-доступ (с rate limit и audit)
• Fallback на человека при низкой уверенности
• Логирование каждого шага (LDD)

Когда переходить дальше: когда fallback rate < 10%, стоимость контура оправдана ROI.

Примеры:

• Автоматический код-ревью + автоисправление + тесты
• Data pipeline: extraction → transformation → validation → load
• Customer support: classify → retrieve → generate → verify → send

Уровень 3: Автобан — масштабирование и мониторинг

Аналогия: вы водите на автобане — высокие скорости, много полос, нужна приборная панель (dashboard) и система предупреждений. Если что-то идёт не так — съезд на обочину (human escalation), а не аварийная остановка.

[Dashboard] ← metrics ← [Multiple Agent Loops] → [Alerts]
                              ↓ anomaly
                         [Human Escalation]

Характеристики:

• Множество агентных контуров работают параллельно
• Централизованный мониторинг (cost, latency, error rate, hallucination rate)
• A/B-тестирование промптов и моделей
• Автоматические алерты на деградацию

Примеры:

• Платформа, обрабатывающая тысячи документов в день
• CI/CD с AI-ревью каждого PR
• Multi-tenant SaaS с AI-функциями

Ключевой принцип: не перескакивайте уровни. Команда, которая пытается сразу строить Уровень 3, обычно откатывается к Уровню 0 через месяц разочарований. Каждый уровень — это не только техническая зрелость, но и доверие команды к AI-инструментам.

Практический rollout-playbook по мотивам GRACE

Если убрать брендовые детали и оставить суть, из grace-marketplace получается очень хороший порядок внедрения AI-friendly engineering в команду:

1. Init. Создайте минимальные проектные артефакты: правила для агента, требования, технологические ограничения, черновой knowledge graph.
2. Plan. До кода опишите модули, границы ответственности, data flows и implementation order.
3. Verification. До больших execution-waves зафиксируйте, как каждый важный модуль будет доказывать корректность: tests, trace markers, required evidence.
4. Execute. Только после этого запускайте worker-агентов на bounded scope.
5. Refresh / Review. После изменений сверяйте shared artifacts с реальным кодом и проверяйте, не возник ли drift.
6. Refactor as migration. Если вы переименовываете, делите или сливаете модули, думайте не «перенёс файл», а «мигрировал код + тесты + graph + verification».

Это ценная методологическая поправка к обычному «просто дайте модели задачу». Самый дешёвый выигрыш в 2026 году часто приходит не от новой модели, а от того, что команда перенесла часть архитектурной памяти из головы людей в репозиторные артефакты.

Минимальная версия этого playbook для небольшой команды может выглядеть совсем просто:

• AGENTS.md или аналог с правилами проекта;
• один planning-документ с модулями и зависимостями;
• один verification-документ с test commands и critical markers;
• file-local contracts на наиболее важных модулях;
• reviewer/refresh-процедура после каждого заметного agent edit.

Такой набор уже создаёт эффект «репозиторий объясняет себя сам», а значит снижает стоимость и для человека, и для coding-агента.

---

23.6. Метрики, которые нужно измерять

Функциональные метрики

Метрика	Что измеряет	Цель
Accuracy	Доля корректных ответов	> 90% (зависит от задачи)
Hallucination rate	Доля ответов с вымышленными фактами	< 5%
Fallback rate	Как часто агент не справляется и передаёт человеку	< 10%
Pass@1	Доля ответов, принятых с первой попытки	> 70%
Loop count	Среднее число итераций контура	< 3

Операционные метрики

Метрика	Что измеряет	Цель
Latency (P50/P95)	Время от запроса до ответа	Зависит от SLA
Cost per request	Стоимость вызовов LLM на запрос	Мониторить тренд
Tokens per request	Средний расход токенов	Оптимизировать
Error rate	Доля технических ошибок (timeout, 500, etc.)	< 1%
Uptime	Доступность сервиса	> 99.5%

ROI формула

Считать ROI удобно в три шага: сначала оценить стоимость ручного труда, затем вычесть стоимость AI-контура и стоимость ошибок AI, а потом разделить полученную чистую экономию на стоимость самого AI-контура.

Где:

• Стоимость ручного труда = (время задачи × ставка специалиста × количество задач/месяц)
• Стоимость AI-контура = (API costs + инфраструктура + DevOps + поддержка)
• Стоимость ошибок AI = (fallback rate × стоимость исправления) + (hallucination rate × стоимость инцидента)

Иллюстративные примеры ROI

Пример 1: Обработка документов (высокий ROI)

• 1000 документов/месяц × 15 мин ручной обработки × $30/час = $7500/мес
• AI-контур: $500 API + $200 инфраструктура + $1000 поддержка = $1700/мес
• Ошибки AI: 5% fallback × $10 + 2% инцидент × $100 = $70/мес
• ROI = ($7500 - $1700 - $70) / $1700 × 100% = 337%

Пример 2: Код-ревью (средний ROI, высокая ценность для скорости)

• 200 PR/месяц × 30 мин ревью × $50/час (senior dev) = $5000/мес
• AI-ревью снижает время на 40%: экономия = $2000/мес
• AI-контур: $300 API (Claude Haiku 4.5 или аналогичный дешёвый tier для первичного ревью) + $100 CI = $400/мес
• Ошибки: 3% пропущенных issues × $200 = $120/мес
• ROI = ($2000 - $400 - $120) / $400 × 100% = 370%
• Бонус: senior-разработчики фокусируются на архитектурных вопросах, а не на стиле кода

Пример 3: Генерация тестов (экономия на self-hosted)

• 500 модулей, покрытие 35% → цель 70%
• Ручные тесты: 2 QA × $4000/мес = $8000/мес
• Self-hosted Llama 4 Scout через vLLM на 1× A100: $2000/мес (GPU) + $500 DevOps = $2500/мес
• Результат: покрытие 68% за 3 недели, ongoing поддержка $2500/мес
• ROI = ($8000 - $2500) / $2500 × 100% = 220%

Пример 4: Негативный ROI — когда НЕ стоит автоматизировать

• 20 контрактов/месяц, юридический анализ
• Ручная работа: юрист × 2 часа × $150/час = $6000/мес
• AI-контур: $800 API + $2000 поддержка + обязательный human review (регуляция) = $2800/мес + $4000 (юрист всё равно проверяет = 80% времени) = $6800/мес
• ROI = ($6000 - $6800) / $6800 × 100% = −12% (дороже, чем без AI)
• Урок: если human-in-the-loop обязателен и занимает почти столько же времени — ROI отрицательный

---

23.7. Типичные ошибки при внедрении

Ошибка 1: начинать с самой сложной задачи

«Давайте сразу заменим весь customer support AI-агентом.»

Проблема: высокая неопределённость, отсутствие метрик, сложные edge cases.

Решение: начать с одного, хорошо определённого use case (например, классификация тикетов), довести до production quality, затем расширять.

Ошибка 2: не логировать

«У нас agent работает, вроде нормально.»

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

Решение: LDD с первого дня. Каждый вызов LLM → лог. Каждый инструмент → лог. Каждая верификация → лог.

Ошибка 3: не ставить ограничения

«Agent может делать до 100 запросов к API.»

Проблема: runaway agent — зацикливание тратит токены/деньги/время.

Решение:

• max_iterations на контур (Глава 13)
• max_tokens на один вызов LLM
• rate_limit на tools
• budget_limit на стоимость одного запроса

Ошибка 4: игнорировать стоимость

«Цена за миллион токенов маленькая, значит об этом можно не думать.»

Проблема: агентный контур с 3 итерациями по 4 вызова LLM × 3000 токенов = 36K токенов на запрос. При 10K запросов/день = 360M токенов/день = $5 400/день (frontier-модель со средней ценой ~$15/MTok). Даже mid-tier модель типа Claude Sonnet ($3–5/MTok) обойдётся в ~$1 080–1 800/день.

Решение:

• Использовать дешёвые модели для рутинных шагов, а frontier — только там, где они реально улучшают метрику
• Self-hosted модели для bulk-операций: Llama 4 Scout/Qwen3/3.5/DeepSeek-V3 через vLLM — фиксированная стоимость GPU вместо оплаты за токены
• Кешировать повторяющиеся запросы
• Prompt caching (Anthropic, OpenAI) для длинных system prompts — экономия зависит от hit rate и длины общего префикса
• Мониторить cost per request, ставить бюджетные алерты
• Стратегия маршрутизации: простые запросы -> mini-модель, сложные -> frontier. Это почти всегда дешевле, чем слать всё в самую дорогую модель

Ошибка 5: не тестировать промпты

«Промпт работал в чате, значит, будет работать в production.»

Проблема: промпт, работающий на 10 примерах, может ломаться на 1000. Edge cases, длинные входы, неожиданные форматы.

Решение:

• Eval-набор из 50–100 примеров (включая edge cases)
• Автоматический прогон при каждом изменении промпта
• Регрессионные тесты: если accuracy упала после изменения → откат

---

23.8. Минимальный запуск: чек-лист первой недели

Самый простой первый проект — автоматический генератор документации для кода. Почему: задача хорошо определена, результат легко проверить (код компилируется, docstring читаема), риск ноль (генерация, а не изменение кода), а eval-набор — это ваш собственный репозиторий.

День 1: Настройка окружения и выбор задачи

• Определить одну задачу для автоматизации (рекомендация для старта: генерация docstrings/комментариев)
• Установить инструменты:
  • Для работы с API: Python 3.11+, pip install openai anthropic (или litellm для единого интерфейса ко всем провайдерам)
  • Для локальных моделей: Ollama — один бинарник, ollama run llama4-scout и модель работает
  • IDE: VS Code + GitHub Copilot или Cursor для ускорения собственной разработки
• Получить API-ключ (OpenAI или Anthropic). Проверьте актуальные условия бесплатного tier'а на сайте провайдера — условия регулярно меняются
• Проверить: python -c "from openai import OpenAI; print('OK')" — всё работает

День 2: Eval-набор и первый промпт

• Собрать eval-набор из 50+ примеров с правильными ответами
  • Для генерации docstrings: 50 функций из вашего проекта + эталонные документации
  • Формат: JSON-файл [{"input": "def foo(x)...", "expected": "Вычисляет..."}]
• Сформулировать критерии успеха (accuracy > X%, latency < Y секунд)
• Выбрать модель: начните с дешёвой mini/flash-модели, которая проходит ваш eval-набор
• Написать первый system prompt (Глава 6: промпт как протокол)

День 3–4: Первый прототип

• Реализовать single-pass pipeline: Input → LLM → Output
  • Фреймворк: чистый Python + openai SDK (не нужен LangChain на старте!)
  • Или: litellm для переключения между провайдерами одной строкой
• Прогнать eval-набор, измерить accuracy
  • Инструменты: promptfoo (open-source eval framework) или просто Python-скрипт
• Итерировать промпт до accuracy > 80%
• Попробовать 2–3 модели на том же eval-наборе, сравнить cost/quality

День 5: Добавить верификацию

• Добавить Verifier (программный или LLM-based)
  • Для docstrings: проверить, что сгенерированный текст не пустой, содержит описание параметров, проходит линтер
• Реализовать fallback: если верификация fail → лог + alert
• Прогнать eval-набор с верификацией, измерить false positive/negative

День 6: Логирование и мониторинг

• Настроить LDD (Глава 13): каждый вызов LLM → лог
  • Минимум: timestamp, model, input_tokens, output_tokens, latency_ms, cost
  • Инструменты: простой JSON-лог файл, или Langfuse/Braintrust для визуализации
• Дашборд: accuracy, latency, cost, fallback rate
• Алерты на аномалии (рост стоимости > 2x, падение accuracy > 10%)

День 7: Production readiness

• Rate limits на все внешние вызовы (библиотека tenacity для retry с backoff)
• Timeout'ы на каждый шаг (30 секунд — разумный дефолт для LLM API)
• Graceful degradation: если LLM API недоступен → fallback (кеш предыдущих ответов или заглушка)
• Документация: что делает контур, как отлаживать, куда смотреть
• Празднование: у вас работающий AI-контур. Это уже Уровень 1.

---

23.9. Идеи первых проектов

Если вы дочитали до этого места и думаете «с чего конкретно начать» — вот пять проектов, отсортированных по сложности. Каждый можно запустить за 1–3 дня.

Проект 1: Генератор документации (сложность: ★)

Что делает: берёт функцию/класс из вашего кода, генерирует docstring.

Стек: Python + OpenAI SDK, GPT-5.4-mini.

Верификация: линтер проверяет формат docstring, человек просматривает выборку.

ROI: экономит 5–10 минут на каждую функцию. При 100 функциях = 8–16 часов.

Проект 2: Классификатор входящих обращений (сложность: ★★)

Что делает: читает письмо/тикет, присваивает категорию и приоритет.

Стек: Python + Claude Haiku 4.5 или другая дешёвая модель с хорошим structured output.

Верификация: confidence score > 0.9 → автоматически, иначе → человеку.

ROI: типичная автоматизация 60–80% тикетов первой линии поддержки.

Проект 3: SQL-ассистент для аналитиков (сложность: ★★)

Что делает: принимает вопрос на естественном языке + схему БД, генерирует SQL.

Стек: Python + любая frontier-модель, schema injection в промпт.

Верификация: EXPLAIN на сгенерированный запрос (синтаксис), dry run, ограничение на SELECT only.

ROI: аналитик получает ответ за 2 минуты вместо 30.

Проект 4: Агент код-ревью для PR (сложность: ★★★)

Что делает: при открытии PR автоматически анализирует diff, оставляет комментарии.

Стек: GitHub Actions + Claude Sonnet 4.6 / GPT-5.4, GitHub API для комментариев.

Верификация: категоризация комментариев (bug / style / suggestion), человек одобряет или отклоняет.

ROI: -40% времени senior-разработчиков на ревью, ускорение цикла merge.

Проект 5: RAG-система по внутренней документации (сложность: ★★★★)

Что делает: индексирует Confluence/Notion/docs, отвечает на вопросы сотрудников с цитатами-источниками.

Стек: Python + embedding-модель + vector DB (Qdrant/ChromaDB) + frontier-модель для генерации.

Верификация: цитаты проверяемы, confidence score, fallback «я не знаю».

ROI: сокращение времени поиска информации с 15–30 минут до 1–2 минут.

---

23.10. Шаблоны eval-наборов для типовых сценариев

Одна из главных трудностей при старте — с чего начать eval-набор. Ниже — шаблоны структуры и примеры для пяти самых распространённых сценариев. Берите шаблон, заполняйте под свой домен.

Сценарий 1: Классификация

Формат eval-записи:

{
  "id": "cls_001",
  "input": "Не могу войти в систему, пишет 'неверный пароль', хотя я его не менял",
  "expected": {
    "category": "account",
    "priority": "high",
    "sentiment": "negative"
  },
  "tags": ["login", "password_error"],
  "difficulty": "easy"
}

Минимальный набор: 50 записей, покрывающих: (a) все категории (минимум 5 примеров на категорию), (b) edge cases (пустой ввод, нецензурная лексика, не на целевом языке), (c) пограничные случаи (текст подходит под 2 категории).

Метрики: Exact match category, F1 per category, confidence calibration.

---

Сценарий 2: Извлечение данных (Extraction)

Формат eval-записи:

{
  "id": "ext_001",
  "input": "Клиент: Иванов Иван, тел. +7-999-123-45-67, заказ №45678 от 15.03.2026, сумма 12 500 руб.",
  "expected": {
    "customer_name": "Иванов Иван",
    "phone": "+7-999-123-45-67",
    "order_number": "45678",
    "date": "2026-03-15",
    "amount_rub": 12500
  },
  "tags": ["russian_names", "phone_format"],
  "difficulty": "medium"
}

Минимальный набор: 50 записей, покрывающих: (a) все форматы полей (разные форматы дат, телефонов, имён), (b) отсутствующие поля (часть данных не указана), (c) неоднозначности (два номера телефона в тексте).

Метрики: Field-level exact match, character-level F1, parse rate.

---

Сценарий 3: Суммаризация

Формат eval-записи:

{
  "id": "sum_001",
  "input": "Документ на 3 страницы про изменение API-политик...",
  "expected": {
    "summary": "Краткое содержание (bullet points): ...",
    "key_points": ["point 1", "point 2", "point 3"],
    "action_items": ["action 1"]
  },
  "tags": ["technical", "api_changes"],
  "difficulty": "hard"
}

Минимальный набор: 30 записей, покрывающих: (a) разные длины входов (от 1 абзаца до 5 страниц), (b) разные домены (технический, юридический, маркетинговый), (c) документы без actionable content.

Метрики: Faithfulness (все ли claims в summary подтверждены исходным текстом?), Completeness (все ли ключевые пункты покрыты?), Conciseness (нет ли «воды»?).

---

Сценарий 4: Кодогенерация

Формат eval-записи:

{
  "id": "code_001",
  "input": "Напиши функцию на Python, которая принимает список int и возвращает медиану. Handle: пустой список, нечётное/чётное количество элементов.",
  "expected": {
    "function_name": "median",
    "test_cases": [
      {"input": "[3, 1, 2]", "expected_output": 2},
      {"input": "[3, 1, 2, 4]", "expected_output": 2.5},
      {"input": "[]", "expected_output": null, "expected_error": "ValueError"}
    ]
  },
  "tags": ["python", "statistics", "edge_cases"],
  "difficulty": "easy"
}

Минимальный набор: 30 записей, покрывающих: (a) простые функции (median, dedup) — 10 шт., (b) средние (JSON parser, CSV reader) — 10 шт., (c) сложные (многопоточность, работа с API) — 10 шт.

Метрики: pass@1 (доля задач, где первый сгенерированный код проходит тесты), code validity (компилируется/запускается без синтаксических ошибок).

---

Сценарий 5: RAG (вопрос-ответ по документам)

Формат eval-записи:

{
  "id": "rag_001",
  "input": "Какой rate limit для Enterprise-клиентов?",
  "context_docs": ["docs/api_limits_v3.md", "docs/pricing_2026.md"],
  "expected": {
    "answer": "1000 запросов в минуту для плана Enterprise",
    "source_doc_ids": ["docs/api_limits_v3.md"],
    "must_not_contain": ["Free план"]
  },
  "tags": ["api", "rate_limits"],
  "difficulty": "medium"
}

Минимальный набор: 50 записей, покрывающих: (a) single-hop вопросы (ответ в одном документе) — 20 шт., (b) multi-hop (ответ требует информации из 2+ документов) — 10 шт., (c) вопросы вне корпуса (должен быть ответ «не знаю») — 10 шт., (d) conflict cases (два документа противоречат) — 10 шт.

Метрики: Faithfulness, context_precision, context_recall, answer_relevancy (RAGAS).

---

Общие правила для всех сценариев

1. Dev/test split: 70% примеров для итеративной разработки промпта, 30% — для финальной оценки перед деплоем. Тестовый сплит не трогайте до последнего прогона.
2. Обновление: Каждый production-инцидент, каждая найденная ошибка → новый тест-кейс в dev-сплите.
3. Формат хранения: JSONL (одна строка — один пример). Версионируйте вместе с кодом в Git.
4. Минимальный размер: 50 примеров для принятия решений, 100+ для статистической значимости.

Промпт для ИИ: «Напиши Python-скрипт для генерации синтетического eval-набора заданного сценария (classification/extraction/summarization/code/rag). Скрипт принимает: тип сценария, описание домена, количество примеров (по умолчанию 50). Использует LLM для генерации разнообразных примеров с вариациями (разные форматы, edge cases). Выход — JSONL-файл, соответствующий шаблонам выше. Проверяет сгенерированные примеры на разнообразие (нет повторов) и покрытие edge cases. Используй OpenAI API или Anthropic API.»

---

23.12. Архитектура развёртывания

Типовая production-архитектура AI-контура в 2026 году:

┌─────────────────────────────────────────────────────────────────┐
│                    PRODUCTION DEPLOYMENT                        │
│                                                                 │
│  ┌──────────┐     ┌──────────────────────────────────────────┐ │
│  │  Клиент   │────▶│            API Gateway                   │ │
│  │ (Web/API/ │     │  Rate limiting, Auth, Request logging    │ │
│  │  CI/CD)   │     └────────────────┬─────────────────────────┘ │
│  └──────────┘                       │                           │
│                                     ▼                           │
│                    ┌────────────────────────────────┐           │
│                    │         Router / Orchestrator   │           │
│                    │  Выбор модели по сложности,     │           │
│                    │  budget control, retry logic     │           │
│                    └───────┬──────────┬──────────────┘           │
│                            │          │                          │
│                   Простые  │          │  Сложные                │
│                   задачи   │          │  задачи                 │
│                            ▼          ▼                          │
│              ┌──────────────┐  ┌──────────────┐                 │
│              │  Self-hosted  │  │  Cloud API   │                 │
│              │  vLLM/llm-d   │  │  (OpenAI,    │                 │
│              │  Llama 4 /    │  │  Anthropic,   │                 │
│              │  Qwen3/3.5    │  │  Google)      │                 │
│              └──────┬───────┘  └──────┬───────┘                 │
│                     │                 │                          │
│                     └────────┬────────┘                          │
│                              ▼                                   │
│                    ┌──────────────────┐                          │
│                    │    Verifier      │                          │
│                    │  Программная +   │                          │
│                    │  LLM проверка    │                          │
│                    └────────┬─────────┘                          │
│                             │                                    │
│                    ┌────────▼─────────┐     ┌────────────────┐  │
│                    │  Result Cache    │     │  Observability │  │
│                    │  (Redis/Memcached)│     │  Logs, Metrics │  │
│                    └────────┬─────────┘     │  Langfuse /    │  │
│                             │               │  Braintrust    │  │
│                             ▼               └────────────────┘  │
│                    ┌──────────────────┐                          │
│                    │   Response API   │                          │
│                    └──────────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

---

Практический вывод

LLM — не замена инженерии, а новый слой инженерии. Разница между «попробовали ChatGPT» и «LLM в production» — это:

1. Протоколы вместо ad-hoc промптов
2. Контуры вместо одиночных вызовов
3. Верификация вместо слепого доверия
4. Логирование вместо чёрного ящика
5. Метрики вместо «вроде работает»
6. Постепенность вместо big bang внедрения

Магия закончилась. Началась инженерия.

Задания

1. Первый eval-набор за 2 часа. Выберите одну задачу из §23.9 (рекомендация: генератор документации). Соберите eval-набор из 50 примеров (25 простых + 25 edge cases). Прогоните через 2 модели разных ценовых tier'ов (например, GPT-5.4-mini и Claude Haiku 4.5). Измерьте accuracy, latency, cost. Ожидаемый результат: таблица сравнения моделей на вашей задаче и выбор стартовой модели.

2. Минимальный агентный контур. По описанию из §23.4 соберите контур Planner → Executor → Verifier → Orchestrator для конкретной задачи вашей команды (например, обработка документов или генерация тестов). Используйте промпт для генерации из §23.4 как основу. Подключите LDD с первого дня: каждый вызов LLM → лог. Прогоните 20 задач, проанализируйте логи. Ожидаемый результат: работающий контур с метриками accuracy, loop count, cost per request.

3. ROI-калькулятор для вашего use case. По формуле из §23.6 рассчитайте ROI для задачи, которую вы хотите автоматизировать. Включите стоимость ручного труда, стоимость AI-контура (API + infra + support) и стоимость ошибок (fallback rate × correction cost + hallucination rate × incident cost). Если ROI < 100% — пересмотрите задачу или модельный tier. Ожидаемый результат: обоснованное решение «автоматизировать / не автоматизировать» с цифрами.

---

Источники

• Anthropic. "Building effective agents." Blog (2024). https://www.anthropic.com/research/building-effective-agents
• OpenAI. "A practical guide to building agents." Cookbook (2025). https://platform.openai.com/docs/guides/agents
• Harrison Chase. "LangGraph: Building Stateful Agents." LangChain Blog (2024). https://langchain-ai.github.io/langgraph/
• Shunyu Yao et al. (2023). "ReAct: Synergizing Reasoning and Acting in Language Models." ICLR 2023.
• Noah Shinn et al. (2023). "Reflexion: Language Agents with Verbal Reinforcement Learning." NeurIPS 2023.
• vLLM Project. "vLLM: Easy, Fast, and Cheap LLM Serving." https://docs.vllm.ai/
• Ollama. "Get up and running with large language models." https://ollama.com/
• SWE-bench. "Can Language Models Resolve Real-World GitHub Issues?" https://www.swebench.com/
• SWE-bench. Official benchmark documentation and leaderboard.
• Ivanov, V. osovv/grace-marketplace README, grace-init, grace-plan, grace-verification, grace-execute, grace-refresh, grace-refactor (2026). Пошаговый rollout-playbook и репозиторные артефакты для AI-friendly engineering.

---

Навигация:

• Назад: Глава 22. Durable orchestration и жизненный цикл агента
• Далее: Глава 24. Ландшафт 2026