init

book/11_tools.md

@@ -0,0 +1,555 @@
+# ГЛАВА 11. НЕ ЗАСТАВЛЯЙ МОДЕЛЬ СЧИТАТЬ — ДАЙ ЕЙ ИНСТРУМЕНТ
+
+Представьте блестящего лингвиста, который свободно говорит на 50 языках, мгновенно схватывает контекст и нюансы, улавливает иронию и подтекст. А теперь попросите его перемножить два четырёхзначных числа в уме. Он попытается — и, скорее всего, ошибётся. Не потому что глуп, а потому что его мозг заточен под другое.
+
+LLM — именно такой лингвист. Просить модель считать — это как просить переводчика доказывать теоремы: он понимает *слова* в формулах, но не выполняет *операции*. Решение очевидно: дай лингвисту калькулятор. Code Interpreter или любой другой **code execution sandbox** — это и есть калькулятор. А в более широком смысле, инструменты (tools) превращают LLM из одинокого эрудита в **менеджера, который знает ЧТО нужно сделать и делегирует КАК — специалистам**: Python считает, база данных ищет, API действует.
+
+Эта глава — о том, почему делегирование работает, и как выстроить архитектуру, в которой модель управляет, а не считает.
+
+---
+
+## 11.1. Почему LLM плохо считают: числовые отношения vs точная арифметика
+
+### Корень проблемы: токенизация чисел
+
+Как мы выяснили в [Главе 1](01_tokens_vectors_and_semantic_space.md), числа токенизируются как текстовые фрагменты, а не как математические объекты:
+
+```
+"247 × 13" → ["247", " ×", " 13"]  — три текстовых токена
+```
+
+Модель не имеет арифметического блока. Она не выполняет умножение. Она **предсказывает**, какие цифры скорее всего следуют за последовательностью `247 × 13 = `. Это принципиально разные операции.
+
+### Что модель может
+
+| Задача | Надёжность | Механизм |
+|--------|------------|----------|
+| Сравнение порядков величин | Хорошо | Статистические ассоциации (`миллион > тысяча`) |
+| Простая арифметика (2 + 3) | Хорошо | Заучено из тренировочных данных |
+| Умножение 2–3-значных | Ненадёжно | Частично заучено, частично угадывает |
+| Умножение 4+ -значных | Плохо | Недостаточно примеров, вероятностная аппроксимация |
+| Проценты и дроби | Ненадёжно | Путает числитель/знаменатель |
+| Статистические расчёты | Плохо | Нет арифметического блока |
+| Float precision | Плохо | `0.1 + 0.2` может дать `0.3` или `0.30000000000000004` |
+
+### Эксперимент: момент истины
+
+Попробуйте прямо сейчас. Откройте любой чат с LLM **без** Code Interpreter и спросите:
+
+```
+"Вычисли 7823 × 4291"
+```
+
+Верный ответ: **33 568 493**.
+
+Модель ответит что-то вроде: `33 571 993` — ошибка на три тысячи. Выглядит правдоподобно, начинается с тех же цифр, но это не результат вычисления — это **статистическая галлюцинация**. Модель предсказала, какие цифры вероятнее всего идут после `7823 × 4291 =`, точно так же, как она предсказывает следующее слово в предложении.
+
+Теперь задайте тот же вопрос модели, у которой включён инструмент выполнения кода:
+
+```python
+print(7823 * 4291)  # → 33568493 ✓
+```
+
+Каждый раз — точный ответ. Не потому что модель стала умнее, а потому что она **делегировала**: написала однострочник на Python и отдала его интерпретатору. Лингвист взял калькулятор.
+
+Усложним: `"Посчитай (7823 × 4291) + (1597 × 863) − 42.7%"`. Без инструмента модель сфантазирует уверенный, но неверный ответ. С Python — выдаст точный результат с промежуточными шагами. Вот почему **Code Interpreter — не фича, а необходимость**.
+
+---
+
+## 11.2. PAL и Tool Use: делегируй вычисление
+
+### PAL: Program-Aided Language Models (пошаговый разбор)
+
+PAL (Gao et al., 2023) — идея элегантна в своей простоте: вместо того чтобы решать задачу самостоятельно, LLM генерирует **программу**, которая решает задачу за неё. Модель остаётся в своей зоне силы — понимание языка и генерация кода, — а вычисления уходят туда, где им место: в интерпретатор.
+
+Разберём по шагам:
+
+**Шаг 1. Входная задача на естественном языке:**
+```
+"В магазине было 48 яблок. Продали 1/3. Потом привезли ещё 20. Сколько яблок?"
+```
+
+**Шаг 2. Модель транслирует текст в код** (это её сильная сторона — понимание текста):
+```python
+apples = 48
+sold = apples // 3  # "продали 1/3" → 16
+remaining = apples - sold  # "осталось" → 32
+delivered = 20  # "привезли ещё 20"
+total = remaining + delivered
+print(total)  # → 52
+```
+
+**Шаг 3. Python выполняет код** и возвращает: `52`
+
+**Шаг 4. Модель формулирует ответ:** «В магазине 52 яблока.»
+
+Обратите внимание: на шагах 1, 2 и 4 работает LLM (язык → код → язык). На шаге 3 — Python (арифметика). Каждый делает то, в чём силён.
+
+**Почему PAL надёжнее, чем Chain-of-Thought арифметика:**
+- Каждый шаг фиксирован в коде — нет скрытых ошибок рассуждения.
+- Арифметика выполняется Python, а не нейронной сетью.
+- Промежуточные значения видимы для отладки.
+- Код можно проверить ревьюером — или другой LLM.
+
+### Паттерн: Code Interpreter / code execution
+
+К 2026 году выполнение кода перестало быть экзотикой, но важно различать **три разные вещи**:
+
+1. **Потребительский продукт** (например, ChatGPT с Advanced Data Analysis).
+2. **API tool** (например, `code_interpreter` у OpenAI или `code_execution` у Anthropic/Gemini).
+3. **Локальный оркестратор** (ваш sandbox, Docker, локальный Python, bash tool).
+
+Во всех трёх случаях идея одна и та же: модель пишет код, а исполняет его отдельная среда. Но включение, права доступа, файловая система и сеть различаются.
+
+Через API схема остаётся явной — вы определяете инструмент в JSON Schema, модель его вызывает. У OpenAI это `tools` с `type: "function"` в Responses API; у Anthropic — `tools` с `input_schema`; у Gemini — `function_declarations`. Все три провайдера используют JSON Schema для описания параметров — определения инструментов фактически переносимы между платформами, а MCP делает эту переносимость стандартом (подробнее — в §11.4).
+
+> **Промпт для генерации:** «Напиши определение tool use-инструмента `execute_python` для [Anthropic Messages API / OpenAI Responses API] — инструмент принимает строку с Python-кодом и возвращает stdout/stderr. Добавь `input_schema` / `parameters` с JSON Schema и обязательное поле `code`. Покажи, как передать этот инструмент в вызов API и как обработать `tool_use` / `tool_calls` в ответе.»
+
+Модель **сама** решает, когда вызвать code execution:
+- Простой факт → ответ из памяти.
+- Вычисление → генерирует Python, запускает, возвращает результат.
+- Визуализация → matplotlib, возвращает изображение.
+- Работа с файлами → читает CSV/JSON, обрабатывает, строит графики.
+
+**Function calling / tool use стал стандартным интерфейсом, но не единым рантаймом.** OpenAI, Anthropic и Google поддерживают структурированные tool-вызовы, а open-weight экосистема научилась их эмулировать через frameworks. Но схемы, approval-flow, JSON-валидация и способность надёжно выбирать нужный инструмент всё ещё отличаются по платформам и моделям.
+
+### Четыре типа инструментов
+
+Инструменты делятся по характеру действия. Это важно для архитектуры — разные типы требуют разных уровней доверия:
+
+**1. Вычисление (computation)** — чистые функции без побочных эффектов:
+| Задача | Инструмент | Почему не LLM |
+|--------|-----------|---------------|
+| Арифметика | Python / Calculator | Нет arithmetic head |
+| Regex | `re` module | Сложные regex → ошибки при генерации |
+| Форматирование | `json.dumps`, `yaml.dump` | Гарантированная структура |
+| Статистика | numpy / pandas | Точность floating point |
+
+**2. Получение данных (data retrieval)** — только чтение, без изменений:
+| Задача | Инструмент | Почему не LLM |
+|--------|-----------|---------------|
+| Поиск фактов | RAG / Web Search | Параметрическая память устаревает |
+| SQL-запросы | База данных (SELECT) | Модель может ошибиться в JOIN |
+| Дата/время | `datetime` / API | Модель не знает «сегодняшнюю» дату |
+| Файлы (чтение) | File system API | Модель не видит файловую систему |
+
+**3. Действия (write/mutate)** — изменения во внешнем мире (требуют подтверждения!):
+| Задача | Инструмент | Риск |
+|--------|-----------|------|
+| Отправка email | SMTP API | Необратимо |
+| Запись в БД | INSERT/UPDATE | Изменяет данные |
+| Создание задачи | Jira / Linear API | Видно команде |
+| Деплой | CI/CD API | Влияет на production |
+
+**4. Коммуникация (communication)** — взаимодействие с пользователями и системами:
+| Задача | Инструмент | Особенность |
+|--------|-----------|------|
+| Уведомления | Slack / Teams API | Проверьте тон и содержание |
+| Ответ пользователю | Chat UI | Финальный этап цепочки |
+| Логирование | Observability API | Для отладки и аудита |
+
+**5. Управление компьютером (computer use)** — прямое взаимодействие с графическим интерфейсом:
+| Задача | Инструмент | Особенность |
+|--------|-----------|------|
+| Действия в браузере | Browser automation / Operator | Навигация, заполнение форм, скриншоты |
+| Взаимодействие с десктопом | Screenshot + mouse/keyboard | Управление приложениями без API |
+| Тестирование UI | Computer Use API | Воспроизведение пользовательских сценариев |
+
+Computer use — качественно новый тип инструмента, появившийся в production-доступе в 2025–2026. В отличие от четырёх предыдущих типов, модель взаимодействует не через API, а через **визуальный интерфейс**: делает скриншот экрана, анализирует его и отправляет команды мыши и клавиатуры. Anthropic предоставляет computer use в бета-режиме (`computer_20251124`), OpenAI — как встроенный инструмент для GPT-5.4 (75 % на бенчмарке OSWorld-Verified).
+
+**Требования к безопасности** у computer use выше, чем у любого другого типа инструментов. Модель видит содержимое экрана — а значит, уязвима к prompt injection через визуальный контент (текст на странице, изображения с инструкциями). Используйте изолированное окружение (Docker, VM) и ограничивайте доступ к чувствительным приложениям.
+
+**Правило большого пальца:** вычисление и чтение — автоматически, действия и коммуникацию — с подтверждением человека (human-in-the-loop). Computer use — всегда с подтверждением и в sandbox.
+
+---
+
+## 11.3. Популярные технологии надёжнее экзотических
+
+### Принцип: ищите не "магическую библиотеку", а кросс-вендорное пересечение
+
+Точный состав тренировочных данных закрытых frontier-моделей мы не видим. Поэтому фразу «эта библиотека точно была в train set у всех вендоров» нельзя честно доказывать по публичным данным. Но есть более надёжный инженерный proxy: **официальные runtime-документы самих платформ**. Когда OpenAI, Anthropic и Gemini независимо сходятся на одном и том же short list для code execution, это сильный сигнал, что именно этот стек будет и доступен, и хорошо поддержан пост-обучением, и привычен модели в инструментальном режиме.
+
+Самое важное наблюдение 2025–2026 годов: у Python-sandbox стеков разных провайдеров действительно есть большое пересечение. Повторяются одни и те же категории: табличная обработка, численные вычисления, графики, файлы Office/PDF, базовая статистика и символьная математика.
+
+### Сверхстабильный short list для Python sandbox
+
+| Категория | Первый выбор | Когда использовать | Почему это надёжно |
+|-----------|--------------|--------------------|--------------------|
+| **Табличные данные** | `pandas` | CSV, Excel, groupby, joins, cleanup | Официально подтверждён у OpenAI; также входит в sandbox Anthropic и Gemini |
+| **Графики** | `matplotlib` | Линейные, столбчатые, scatter, отчётные chart'ы | OpenAI прямо говорит про Matplotlib; Gemini поддерживает только `matplotlib` для graph rendering |
+| **Численные вычисления** | `numpy`, `scipy` | массивы, статистика, оптимизация, scientific helpers | Есть в Anthropic и Gemini; это де-факто базовый численный слой Python |
+| **Excel I/O** | `openpyxl` | читать/писать `.xlsx`, править workbook'и | Повторяется в Anthropic и Gemini |
+| **Базовая статистика и ML** | `scikit-learn`, `statsmodels` | регрессии, baseline-классификация, простые метрики | Явно перечислены в Anthropic; `scikit-learn` также есть у Gemini |
+| **Символьная математика** | `sympy` | формулы, уравнения, algebraic manipulation | Есть в Anthropic и Gemini |
+| **Документы и отчёты** | `python-docx`, `python-pptx`, `reportlab` | DOCX/PPTX/PDF-артефакты | Anthropic и Gemini публикуют похожий набор |
+| **Файлы и изображения** | `pillow`, `pypdf`/`PyPDF2` | изображения, PDF, file transformations | Стабильная часть sandbox-экосистемы Anthropic и Gemini |
+
+Это не строгая теорема про training mix, но очень полезная operational policy: если агент может решить задачу на этом short list, почти всегда стоит начать именно с него.
+
+### JS и artifact-side: React как безопасный первый выбор
+
+На JavaScript-стороне картина менее симметрична, потому что многие платформы выполняют код именно в Python, а не в Node.js sandbox. Но для Claude есть очень явный сигнал: в официальной документации по Artifacts среди типовых результатов и AI-powered UI прямо фигурируют **interactive React components** и rich UIs with React. Поэтому для browser-side прототипов, мини-инструментов и UI-обвязки вокруг модели разумный default — **React-first**, а не экзотический frontend-стек.
+
+Практический перевод этого наблюдения простой: если ваша цель — быстро получить рабочий AI-артефакт или интерактивный инструмент, React почти всегда безопаснее, чем niche framework с маленьким следом в экосистеме.
+
+### Вне песочницы действует тот же принцип
+
+Даже когда задача не сводится к sandbox-коду, общая закономерность сохраняется: mainstream-технологии модель генерирует и чинит надёжнее, чем редкие или слишком новые.
+
+| Технология | Представленность в открытой экосистеме | Качество генерации |
+|------------|----------------------------------------|-------------------|
+| Python + `requests` / `httpx` | Очень высокая | Отлично |
+| JavaScript + `fetch` | Очень высокая | Отлично |
+| SQL (PostgreSQL, MySQL) | Очень высокая | Хорошо |
+| Go + `net/http` | Высокая | Хорошо |
+| Rust + `tokio` | Высокая и растущая | Хорошо |
+| Terraform / Kubernetes YAML | Высокая | Хорошо |
+| React / Next.js | Очень высокая | Хорошо |
+| Elixir + Phoenix | Умеренная | Средне |
+| Zig / V / Nim | Низкая | Ненадёжно |
+| Кастомный DSL | Почти нулевая | Плохо без few-shot и валидации |
+
+### Как определить preferred stack в новой среде
+
+1. **Смотрите официальные docs runtime-а**, а не только бенчмарки модели. Если платформа перечисляет preinstalled libraries или официальные способы рендеринга, это сильнее догадок о train set.
+2. **Ищите пересечение между провайдерами.** Чем больше overlap у OpenAI, Anthropic, Gemini и похожих сред, тем выше шанс, что решение будет переносимым.
+3. **Отмечайте библиотеки из официальных примеров.** Если документация снова и снова показывает `pandas`, `matplotlib` и `React`, это хороший сигнал для default choice.
+4. **Проверяйте sandbox-ограничения.** Например, Gemini разрешает много библиотек, но для графиков официально поддерживает именно `matplotlib`; значит, `matplotlib-first` — не эстетический выбор, а operational constraint.
+
+### Как использовать short list эффективно
+
+1. В system prompt или project rules явно пишите: **"сначала решай задачу на standard stack"**.
+2. Для таблиц начинайте с `pandas`; переходите к `numpy`/`scipy`, только если нужен более низкий уровень математики.
+3. Для графиков default = `matplotlib`, если вам важна переносимость между sandboxes.
+4. Для Excel используйте `openpyxl`, а не малоизвестные обёртки.
+5. Для символьных задач используйте `sympy`, а не самодельный парсер формул.
+6. Для AI-артефактов и UI-прототипов в Claude задавайте React как предпочтительный frontend.
+7. Разрешайте переход на niche library только после короткого объяснения, почему short list недостаточен.
+
+> **Практический policy-prompt:** «При работе в sandbox предпочитай следующий стек по умолчанию: `pandas`, `matplotlib`, `numpy`, `scipy`, `openpyxl`, `scikit-learn`, `sympy`, `pillow`, `python-docx`, `python-pptx`, `reportlab`. Сначала предлагай решение на этом стеке. Переход на нишевую библиотеку допускается только если ты кратко объяснил, почему standard stack не покрывает задачу. Для UI-артефактов предпочитай React.»
+
+### Практические рекомендации
+
+1. **Python + стандартная библиотека + short list** — первый выбор для вычислений и data tasks.
+2. **`ast` + sandbox** — для безопасного выполнения сгенерированного кода.
+3. **Стандартные API** (REST, GraphQL) — для интеграций.
+4. **Проверенные библиотеки** (`pandas`, `numpy`, `openpyxl`, `matplotlib`) — раньше кастомных обёрток.
+5. **Фреймворки оркестрации** (LangChain Tools, LlamaIndex Tools, Anthropic tool use, OpenAI Responses API) — стандартные паттерны вместо велосипедов.
+
+> **Промпт для генерации песочницы:** «Напиши Python-функцию `safe_execute(code: str) -> (stdout, stderr)` для безопасного выполнения LLM-сгенерированного кода. Требования: (1) AST-проверка — запретить import os/subprocess/shutil/sys и вызовы exec/eval/\_\_import\_\_; (2) ограниченный `__builtins__` — только print, range, len, числовые типы, коллекции, sorted, enumerate; (3) перехват stdout через StringIO; (4) timeout через signal или threading. Для production предпочтительнее Docker/VM-песочница или серверный инструмент (`code_execution` у Anthropic, `code_interpreter` у OpenAI).»
+
+---
+
+## 11.4. Экосистема MCP: как модели получили доступ ко всему
+
+### Что такое MCP
+
+Model Context Protocol (MCP) — открытый стандарт, который позволяет LLM подключаться к внешним инструментам через единый интерфейс. Если function calling — это способность модели вызывать функции, то MCP — это стандартизация того, **как эти функции обнаруживаются, описываются и вызываются**. Думайте о нём как о USB для AI: один разъём, много устройств.
+
+MCP создан Anthropic в конце 2024 года, но к 2025 году перешёл под управление **Linux Foundation** (LF Projects, LLC) и управляется MCP Steering Group. Текущая версия спецификации — `2025-11-25`. Протокол построен на JSON-RPC 2.0 и поддерживает два транспорта: **STDIO** (локальный процесс, без сетевых задержек) и **Streamable HTTP** (удалённые серверы, поддержка OAuth-аутентификации).
+
+MCP-сервер предоставляет клиенту три типа примитивов:
+- **Tools** — вызываемые функции (discovery через `tools/list`, исполнение через `tools/call`).
+- **Resources** — источники данных для контекста (файлы, БД, API).
+- **Prompts** — переиспользуемые шаблоны взаимодействия.
+
+Базовая концепция MCP и её связь с агентным контуром рассмотрены в [Главе 10](10_agent_not_chat.md). Здесь мы сосредоточимся на экосистеме, нативной поддержке в API и принципах выбора серверов.
+
+### Нативная поддержка MCP в API провайдеров
+
+Ключевое событие 2025–2026: оба крупнейших провайдера встроили MCP-клиент прямо в свои API. Это значит, что один MCP-сервер, написанный один раз, работает и с Claude, и с ChatGPT, и с VS Code, и с десятками других клиентов.
+
+| Провайдер | Механизм | Что поддерживается |
+|-----------|----------|-------------------|
+| **OpenAI** | `type: "mcp"` в Responses API | Удалённые MCP-серверы (Streamable HTTP, SSE). Connectors — готовые MCP-обёртки для Dropbox, Gmail, Google Drive, Outlook, Teams, SharePoint и др. |
+| **Anthropic** | MCP Connector в Messages API (бета-заголовок `mcp-client-2025-11-20`) | Удалённые MCP-серверы по URL. Пока только tool calls (не resources/prompts через API). |
+| **VS Code / Copilot** | Встроенная поддержка MCP-серверов | Локальные и удалённые серверы, конфигурация в settings |
+| **Cursor, Claude Code** | Конфигурация MCP-серверов | Поддержка STDIO и HTTP транспортов |
+
+Не все клиенты поддерживают все примитивы — в production проверяйте transport, approval-flow и security-модель конкретного клиента.
+
+### Экосистема MCP-серверов в 2026 году
+
+К апрелю 2026 года экосистема MCP взрывно выросла: 80 000+ звёзд на GitHub, 100+ официальных интеграций, 10+ SDK на разных языках (официальные: TypeScript, Python; community: Java, Kotlin, Go, Rust, C#, Ruby, PHP, Swift).
+
+| Категория | Примеры MCP-серверов | Что даёт модели |
+|-----------|----------------------|------------------|
+| Базы данных | PostgreSQL, SQLite, MongoDB, Snowflake | Чтение/запись данных |
+| API и SaaS | GitHub, Slack, Jira, Linear, Stripe | Управление проектами и сервисами |
+| Файловые системы | Локальные файлы, Google Drive, S3 | Чтение/запись файлов |
+| Инфраструктура | Kubernetes, Docker, AWS, Cloudflare | Управление инфраструктурой |
+| Поиск | Brave Search, Google, Exa | Веб-поиск в реальном времени |
+| Разработка | Git, терминал, LSP, Firebase | Работа с кодом и репозиториями |
+| Мониторинг | Sentry, Datadog, Grafana | Анализ логов и метрик |
+
+Для создания собственных MCP-серверов существуют фреймворки: FastMCP, Spring AI MCP, Quarkus MCP, Vercel MCP Adapter — и даже автогенераторы из OpenAPI-спецификаций (FastAPI-to-MCP).
+
+### Как найти нужный MCP-сервер
+
+- **MCP реестр** (modelcontextprotocol.io) — каталог проверенных серверов, управляемый MCP Steering Group.
+- **GitHub** — поиск по `topic:mcp-server`.
+- **npm / PyPI** — пакеты с префиксом `mcp-server-*`.
+- **OpenAI Connectors** — готовые интеграции для популярных SaaS (не требуют отдельного MCP-сервера).
+
+### A2A: протокол для взаимодействия агентов
+
+MCP решает задачу «агент ↔ инструмент». Но что если нужно, чтобы **агент взаимодействовал с другим агентом** — например, агент-планировщик делегирует подзадачу агенту-исполнителю на другом сервере?
+
+Для этого Google предложил **A2A (Agent-to-Agent Protocol)** — протокол обнаружения и коммуникации между автономными агентами. A2A и MCP не конкурируют, а дополняют друг друга: MCP стандартизирует доступ к инструментам и данным, A2A — оркестрацию между агентами. Существует «A2A MCP Server» — мост, позволяющий MCP-клиенту вызывать A2A-агентов как обычные инструменты.
+
+В production-системах с несколькими специализированными агентами стоит рассматривать связку MCP + A2A. Для систем с одним агентом и набором инструментов — достаточно MCP.
+
+### Пример: как модель использует MCP
+
+```
+Пользователь: "Какие баги были заведены на этой неделе?"
+
+Модель (думает): Нужна информация из Jira → вызову MCP-сервер Jira
+Модель → MCP Jira: tools/call search_issues(type="Bug", created_after="2026-04-03")
+MCP Jira → Модель: [список из 12 багов с ключами, статусами, assignee]
+Модель → Пользователь: "На этой неделе заведено 12 багов, из них 3 критичных..."
+```
+
+Модель выступила менеджером: поняла запрос, выбрала нужный инструмент, сформулировала параметры и пересказала результат человеческим языком.
+
+---
+
+## 11.5. Принципы проектирования инструментов
+
+Недостаточно дать модели инструменты — нужно, чтобы она **понимала**, когда и как их использовать. Это целиком зависит от того, как вы опишете инструмент.
+
+### 1. Имя: глагол + существительное
+
+```
+✓ search_issues, create_user, get_file_contents, run_sql_query
+✗ do_thing, helper, process, handle  ← модель не поймёт, когда вызывать
+```
+
+### 2. Описание: когда использовать, а не только что делает
+
+```
+✗ Плохое описание:
+"description": "Search for issues"          ← какие issues? когда?
+
+✓ Хорошее описание:
+"description": "Search Jira issues by type, status, assignee, or date range.
+                Use when the user asks about bugs, tasks, or project progress.
+                Returns issue key, title, status, and assignee."
+```
+
+### 3. Параметры: строгая типизация + enum где возможно
+
+```
+✗ Модель будет гадать формат:
+"date": {"type": "string"}
+
+✓ Формат явный:
+"date": {"type": "string", "format": "date", "description": "ISO 8601: YYYY-MM-DD"}
+"status": {"type": "string", "enum": ["open", "in_progress", "closed"]}
+```
+
+### 4. Меньше инструментов — лучше
+
+Каждый инструмент в списке — это токены в контексте. 5–15 инструментов — оптимально. 50+ — модель начнёт путаться и выбирать не тот. Лучше один инструмент `search_database(query, table)`, чем десять `search_users`, `search_orders`, `search_products`...
+
+**Tool search: масштабирование за 15 инструментов.** Правило «5–15 инструментов» работает при передаче всех определений в контекст. Но в MCP-экосистемах с десятками серверов и сотнями инструментов это ограничение становится проблемой. GPT-5.4 (OpenAI, март 2026) ввёл **tool search** — механизм, при котором модель получает лёгкий индекс инструментов (имя + краткое описание), а полные определения подгружает по запросу. По данным OpenAI, tool search снизил потребление токенов примерно вдвое при сохранении accuracy на внутреннем бенчмарке с десятками MCP-серверов (детали методологии не опубликованы).
+
+Если вы строите систему с большим числом MCP-серверов — проверьте, поддерживает ли ваш клиент lazy tool loading. Это реальный рычаг снижения стоимости inference в агентных контурах.
+
+### 5. Возвращайте структурированные данные, не прозу
+
+Модель лучше работает с JSON, чем с произвольным текстом. Возвращайте `{"count": 12, "critical": 3, "items": [...]}`, а не `"Found 12 bugs, 3 critical"`.
+
+---
+
+## 11.6. Шкала важности 1–10: используйте для ранжирования, не для метрик
+
+### Проблема с абсолютными числами
+
+Когда вы просите модель: «Оцени важность по шкале от 1 до 10», она возвращает число. Но это число **не калибровано**: модель не имеет внутренней шкалы, привязанной к реальности.
+
+```
+Промпт: "Оцени серьёзность бага по шкале 1-10"
+Баг: "Опечатка в логе" → Модель: "3"
+Баг: "SQL injection" → Модель: "9"
+Баг: "Race condition в платёжном модуле" → Модель: "8"
+```
+
+Проблема: **8 vs 9** — значимая разница? Или модель просто случайно выбрала числа? При повторном запуске может быть 7 и 8 или 9 и 9.
+
+### Когда числовые оценки полезны
+
+**Для ранжирования** (relative ordering): модель стабильно ставит SQL injection выше опечатки. Порядок надёжнее абсолютных значений.
+
+**Для категоризации** (binning): `1–3 = low`, `4–7 = medium`, `8–10 = high`. Широкие бины устойчивы к шуму.
+
+### Когда использовать инструменты вместо оценок
+
+| Задача | LLM-оценка | Инструмент |
+|--------|------------|-----------|
+| «Насколько сложен код?» | Субъективно | Cyclomatic complexity (radon) |
+| «Насколько длинный текст?» | Угадывает | `len(text.split())` |
+| «Какой прирост производительности?» | Не может | Benchmark (timeit) |
+| «Уязвим ли код?» | Может пропустить | SAST tools (semgrep, bandit) |
+| «Соответствует ли API стандарту?» | Неточно | Schema validator |
+
+---
+
+## 11.7. Архитектура: LLM как менеджер, не исполнитель
+
+### Правильная ментальная модель
+
+LLM — это менеджер, который прекрасно понимает, ЧТО нужно сделать, но не должен делать всё сам. Как хороший руководитель, он делегирует КАК специалистам:
+
+```
+LLM = Менеджер (понимание задачи, планирование, коммуникация)
+Python = Бухгалтер (вычисления)
+БД    = Архивариус (поиск данных)
+API   = Курьер (действия во внешнем мире)
+```
+
+LLM решает **что** делать и **почему**. Tools выполняют **как**:
+
+```
+┌─────────────────────────────┐
+│           LLM               │
+│  "Нужно посчитать налог"    │
+│  → Сгенерировать Python     │
+│  → Результат: $12,450       │
+│  → Сформировать ответ       │
+└───────────┬─────────────────┘
+            │ tool call
+            ▼
+┌─────────────────────────────┐
+│     Python Executor         │
+│  income = 85000             │
+│  tax = income * 0.22        │
+│  deductions = 6300          │
+│  total = tax - deductions   │
+│  → return 12450.0           │
+└─────────────────────────────┘
+```
+
+### Anti-pattern: заставлять LLM быть калькулятором
+
+```
+✗ "Посчитай стоимость 247 единиц товара по $13.99 каждая, 
+    с НДС 20%, скидкой 5% для объёма > 200 единиц"
+
+✓ "Сгенерируй Python-код для расчёта стоимости:
+    - Количество: 247
+    - Цена за единицу: $13.99
+    - НДС: 20%
+    - Скидка: 5% (при объёме > 200)
+    Выведи промежуточные значения и финальную сумму."
+```
+
+---
+
+## 11.8. Computer use и browser automation
+
+### Сдвиг парадигмы: от API к UI-действиям
+
+Не все системы имеют API. Legacy-приложения, внутренние порталы, сторонние SaaS без публичного интерфейса — единственный способ автоматизации для них — это взаимодействие с графическим интерфейсом. Computer use (Anthropic) и browser automation (OpenAI Operator, Playwright-based агенты) превращают GUI в ещё один tool surface.
+
+Важно: это **не** screen scraping и не macro-recording. Модель анализирует скриншот, распознаёт элементы интерфейса, принимает решение о следующем действии на основе текущего визуального состояния. Каждый шаг — полноценный inference-вызов с reasoning, а не воспроизведение записанного сценария.
+
+В §11.2 мы выделили computer use как пятый тип инструментов. Здесь — инженерная механика: как это работает, где ломается и когда стоит применять.
+
+### Механика: screenshot → perception → action
+
+Цикл computer use повторяет стандартный agent loop ([Глава 10](10_agent_not_chat.md)), но вместо JSON-ответа от API модель получает **изображение** экрана:
+
+1. **Screenshot** — агент делает снимок экрана (или окна браузера) и передаёт его модели как изображение.
+2. **Perception** — vision-capable модель анализирует скриншот: распознаёт кнопки, поля ввода, текст, меню.
+3. **Action** — модель возвращает действие: `click(x, y)`, `type("text")`, `scroll(direction)`, `key("Enter")`.
+4. **Re-screenshot** — после выполнения действия делается новый скриншот, и цикл повторяется.
+
+Две ключевые проблемы механики:
+
+- **Coordinate scaling.** Координаты клика зависят от разрешения скриншота. Если скриншот сделан в одном разрешении, а действие выполняется в другом — промах мимо элемента. Решение: фиксированное разрешение скриншотов и нормализация координат.
+- **Нестабильность UI.** Интерфейс — живая система: появляются popup-окна, элементы перемещаются после загрузки, страница перерисовывается. Нужна retry-логика с повторным скриншотом и переоценкой ситуации.
+
+### Инженерные проблемы
+
+| Проблема | Суть | Решение |
+|----------|------|--------|
+| Sandboxing | Агент имеет доступ ко всему экрану — файлы, пароли, другие приложения | Запуск в изолированной VM или контейнере с минимальным набором приложений |
+| Prompt injection через UI | Вредоносный контент на странице может перенаправить агента (текст, изображение с инструкцией) | Фильтрация OCR-контента, ограничение доменов, мониторинг отклонений от плана |
+| Coordinate scaling | Разрешение скриншота ≠ разрешение экрана → промахи | Фиксированное разрешение, калибровка координат |
+| Approval gates | Необратимые действия: удаление данных, оплата, отправка сообщений | Human-in-the-loop checkpoint перед каждым destructive action |
+| End-to-end верификация | Как убедиться, что действие выполнено корректно | Post-action screenshot → LLM-верификация результата |
+| Observability | Отладка GUI-автоматизации значительно сложнее отладки API-вызовов | Запись видео сессии, логирование каждого шага с скриншотом и action |
+
+### Когда использовать, а когда нет
+
+**Используй computer use, когда:**
+- Нет API (legacy-система, внутренний портал, сторонний SaaS).
+- Нужна визуальная верификация (проверить, что UI отображает правильные данные).
+- End-to-end тестирование пользовательских сценариев.
+- Прототипирование автоматизации до появления API-интеграции.
+
+**НЕ используй, когда:**
+- Есть API — он всегда предпочтительнее по скорости, надёжности и стоимости.
+- Нужна высокая скорость — каждый шаг computer use требует inference-вызов + screenshot.
+- Нужна надёжность >99% — GUI нестабилен, элементы смещаются, появляются рекламные баннеры.
+- Обрабатываются чувствительные данные без возможности изолировать окружение.
+
+### Безопасность
+
+Computer use — самый рискованный тип инструмента из пяти, описанных в §11.2. Модель видит содержимое экрана целиком и может выполнять произвольные действия с клавиатурой и мышью. Ключевое правило: **computer use agent работает в sandbox с минимальными привилегиями**. Не давайте доступ к production-системам без approval gate.
+
+Подробный разбор атак на computer use — включая визуальный prompt injection, click-jacking через UI-элементы и эксфильтрацию данных через скриншоты — в [Главе 15](15_llm_system_security.md), секции 15.5–15.6.
+
+---
+
+## Практический вывод
+
+### Чек-лист делегирования
+
+| # | Правило | Действие |
+|---|---------|----------|
+| 1 | **Никогда не доверяйте арифметике модели** | Используйте code execution / calculator tool |
+| 2 | **Используйте function calling** | Определите tools для вычислений, поиска, API |
+| 3 | **Валидируйте типы и диапазоны** | Результат tool → проверка перед возвратом пользователю |
+| 4 | **Логируйте вызовы инструментов** | Для отладки и аудита |
+| 5 | **Предпочитайте mainstream** | Python > кастомный DSL |
+| 6 | **Sandbox** | Изолированное выполнение сгенерированного кода |
+| 7 | **Числовые оценки → для ранжирования** | Не для абсолютных метрик |
+| 8 | **Проектируйте инструменты для модели** | Чёткие имена, описания, типы, enum |
+| 9 | **Используйте MCP** | Стандартный протокол вместо кастомных интеграций |
+| 10 | **Computer use — в sandbox** | Изолированное окружение + human-in-the-loop |
+| 11 | **Computer use — не замена API** | Если есть API, используйте API |
+
+### Задания
+
+**Задание 1. Проектирование набора инструментов.** Выберите реальный рабочий сценарий (например, «агент-помощник для DevOps» или «аналитик данных»). Составьте список из 5–10 инструментов, классифицируйте каждый по пяти типам из §11.2 и напишите для каждого: имя (глагол + существительное), description с указанием «когда использовать», JSON Schema параметров с типами и enum. Ожидаемый результат: готовый к использованию набор tool-определений, который можно подключить к любому провайдеру.
+
+**Задание 2. MCP — от нуля до рабочего сервера.** С помощью FastMCP или официального SDK (см. modelcontextprotocol.io) создайте MCP-сервер для внутреннего сервиса вашей команды (например, внутренняя вики или трекер задач). Реализуйте 2–3 инструмента и подключите сервер к Claude Desktop или VS Code. Ожидаемый результат: работающий MCP-сервер, который модель обнаруживает и вызывает в ответ на пользовательские запросы.
+
+**Задание 3. Делегирование vs самостоятельный ответ.** Составьте набор из 10 запросов, которые примерно поровну делятся на «модель справится сама» и «нужен инструмент». Отправьте их модели без инструментов и с инструментами, сравните результаты. Ожидаемый результат: понимание границы, где делегирование даёт выигрыш, а где добавляет лишнюю латентность.
+
+---
+
+## Источники
+- Gao, L., et al. (2023). "PAL: Program-aided Language Models." ICML.
+- Schick, T., et al. (2023). "Toolformer: Language Models Can Teach Themselves to Use Tools." NeurIPS 2023. arXiv:2302.04761.
+- Model Context Protocol Specification. (2025). LF Projects, LLC. https://spec.modelcontextprotocol.io/specification/ — spec version `2025-11-25`.
+- MCP Servers Repository. https://github.com/modelcontextprotocol/servers
+- OpenAI. “Tools, Connectors, and MCP.” Responses API Documentation. https://developers.openai.com/api/docs/guides/tools-connectors-mcp
+- Anthropic. “MCP Connector.” Claude Documentation. https://platform.claude.com/docs/en/agents-and-tools/mcp-connector
+- Anthropic. “Tool Use.” Claude Documentation. https://platform.claude.com/docs/en/agents-and-tools/tool-use
+- Anthropic. “Computer Use.” Claude Documentation. https://platform.claude.com/docs/en/agents-and-tools/computer-use
+- OpenAI. (2026). *Introducing GPT-5.4* — tool search, computer use. https://openai.com/index/introducing-gpt-5-4/
+- Google. (2025). “Agent-to-Agent Protocol (A2A).” https://github.com/google/A2A
+- Qin, Y., et al. (2024). “Tool Learning with Foundation Models.” Nature Machine Intelligence.
+- OpenAI. “Data analysis with ChatGPT.” Help Center (updated 2026). pandas + Matplotlib, secure code execution environment with hundreds of Python libraries. https://help.openai.com/en/articles/8437071-data-analysis-with-chatgpt
+- Anthropic. “Code execution tool.” Claude API docs (2026). Pre-installed libraries for data science, visualization, file processing and math. https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
+- Google. “Code execution.” Gemini API docs (updated 2026-03-25). Supported libraries and `matplotlib`-only graph rendering. https://ai.google.dev/gemini-api/docs/code-execution
+- Anthropic Help Center. “What are artifacts and how do I use them?” Interactive React components and AI-powered artifacts with React. https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them
+
+---
+
+**Навигация:**
+- Назад: [Глава 10. Агент ≠ Чат: разные режимы, разные правила](10_agent_not_chat.md)
+- Далее: [Глава 12. RAG: когда модели не хватает собственных знаний](12_rag.md)