# ГЛАВА 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](24_landscape_2026.md). Вот дерево решений:

```
                        ┌─ Задача требует рассуждений,
                        │  длинного контекста, сложной
                        │  генерации кода?
                        │
                   ДА ──┤                    НЕТ ──┐
                        │                          │
                        ▼                          ▼
            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](10_agent_not_chat.md).

**Компонент 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 репозитория

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

```text
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](13_anti_hallucination_loop.md))
- `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](https://ollama.com) — один бинарник, `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](06_prompt_is_a_protocol.md): промпт как протокол)

### День 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](13_anti_hallucination_loop.md)): каждый вызов 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.11. Шаблоны eval-наборов для типовых сценариев

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

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

**Формат eval-записи:**
```json
{
  "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-записи:**
```json
{
  "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-записи:**
```json
{
  "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-записи:**
```json
{
  "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-записи:**
```json
{
  "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 и жизненный цикл агента](22_durable_orchestration_and_agent_lifecycle.md)
- Далее: [Глава 24. Ландшафт 2026](24_landscape_2026.md)
