Раздел 49 · Агенты и LLM-разработка: типография «Оттиск»

Болванка

middle~30 мин

без входаВойди, чтобы отмечать прогресс, вести заметки и решать задачи в редакторе. войти

Сан Саныч не уходит. Он садится на табурет у твоего стола, достаёт из кармана халата сложенный листок и разворачивает: два ответа pi на один и тот же вопрос, один под другим.

Сан Саныч назвал главную трудность. В прошлом уроке ты запустил приёмщика pnpm hello на настоящей модели. Код приёмщика твой, и его надо проверять тестами, как любой другой код. Но тест должен давать один и тот же результат на одном и том же коде, работать без сети и ничего не стоить. Настоящая модель не даёт ни одного из трёх.

В этом уроке ты увидишь, как курс решает эту задачу: тесты зовут Болванку, модель-дублёра, которая отвечает по сценарию. Ты разберёшь, как устроен сценарий, что такое условие хода и повторяемый ход, что значит «ход не найден», и напишешь первый сценарий сам.

Почему тест не зовёт настоящую модель

Три причины, по одной на каждое свойство теста.

Ответ каждый раз другой. Модель выбирает каждый следующий токен с долей случайности, поэтому на один и тот же запрос пишет разные ответы. Она недетерминирована. Код может быть правильным, а тест, который сверяет текст ответа, будет то зелёным, то красным. Как устроена эта случайность и почему её не выключить до конца, разберёшь в девятом уроке.

Каждый прогон стоит денег. Тесты курса запускаются тысячи раз: у каждого ученика, при каждой проверке. Даже по долям цента за прогон набегает счёт, который никто не закладывал.

Нужны сеть и ключ. Задачи курса идут в браузере, в песочнице на странице урока. Ключа DeepSeek там нет и быть не должно: всё, что попало в браузер, может прочитать любой, кто открыл страницу.

Есть и четвёртая причина, тоньше. Тест проверяет твой код, а не модель. Приёмщик должен отправить модели вопрос и описание инструмента, исполнить вызов price, вернуть результат с правильным id вызова и не зациклиться. Всё это можно проверить, если на месте модели стоит кто-то, кто играет заранее известную роль. Насколько хорошо модель отвечает клиентам, это другой вопрос, и меряют его другим способом: эвалами в модуле AG13.

Болванка

Сан Саныч кивает: в цеху тоже проверяли, не тратя тиража.

Болванка курса устроена так же. Это модель-дублёр: снаружи она говорит на том же протоколе, что настоящая модель, а внутри у неё нет ничего, кроме сценария. Тест заранее пишет, что Болванка ответит, и проверяет, что твой код сделает с этим ответом.

Протокол у Болванки от OpenAI: она принимает тот же запрос POST …/chat/completions и отвечает тем же JSON, что настоящая модель. На этом протоколе говорит SDK openai, и на нём же отвечают DeepSeek, OpenRouter и другие поставщики моделей. Поэтому один и тот же код работает и с Болванкой, и с DeepSeek.

Один код, два клиента

Весь приём держится на одном решении: код приёмщика не создаёт клиента модели сам, а получает его параметром. Вот answer из шаблона, сокращённо:

export const answer = async (client: OpenAI, model: string, question: string): Promise<Answer> => {
  const messages: ChatCompletionMessageParam[] = [
    { role: 'system', content: SYSTEM },
    { role: 'user', content: question },
  ];
  let promptTokens = 0;
  let completionTokens = 0;
  for (let step = 0; step < 3; step++) {
    const response = await client.chat.completions.create({ model, messages, tools: [PRICE_TOOL] });
    promptTokens += response.usage?.prompt_tokens ?? 0;
    completionTokens += response.usage?.completion_tokens ?? 0;
    const message = response.choices[0]?.message;
    if (!message) throw new Error('модель не ответила');
    messages.push(message);
    const calls = (message.tool_calls ?? []).filter((call) => call.type === 'function');
    if (calls.length === 0) return { text: message.content ?? '', promptTokens, completionTokens };
    for (const call of calls) {
      messages.push({ role: 'tool', tool_call_id: call.id, content: price(call.function.arguments) });
    }
  }
  throw new Error('приёмщик не ответил за три шага');
};

По строкам:

  • messages это разговор: системная инструкция «ты приёмщик, цены бери только из price» и вопрос клиента.
  • client.chat.completions.create отправляет модели весь разговор и описание инструмента price.
  • usage в ответе это токены на входе и на выходе. Приёмщик складывает их по шагам, отсюда строка «Токены» в pnpm hello.
  • Ответ модели ложится в разговор: следующий запрос уйдёт уже с ним.
  • Нет вызовов, значит, модель ответила текстом, и приёмщик его возвращает.
  • Есть вызовы, значит, приёмщик исполняет price и кладёт результат в разговор с tool_call_id, чтобы результат был привязан к своей заявке.
  • Три шага это предохранитель: модель, которая зовёт price без конца, не съест бюджет.

Кто стоит за client, функция не знает. В шаблоне у себя это DeepSeek:

new OpenAI({ baseURL: 'https://api.deepseek.com', apiKey: config.apiKey });
// модель: 'deepseek-flash'

Проверено на: DeepSeek deepseek-flash, 2026-11-11.

А в тесте курса это Болванка:

const model = bolvanka(scenario);
const client = new OpenAI({
  apiKey: 'bolvanka',
  baseURL: 'http://bolvanka/v1',
  fetch: model.fetch,
  dangerouslyAllowBrowser: true,
});
  • bolvanka(scenario) создаёт Болванку по сценарию и отдаёт два поля: fetch и seen.
  • fetch это опция SDK: функция, которой клиент отправляет HTTP-запросы. Обычно это fetch браузера или Node, и запрос уходит в сеть. Здесь вместо неё функция Болванки: запрос до сети не доходит, Болванка читает его тело и сразу отвечает.
  • baseURL и apiKey нужны SDK, чтобы собрать запрос, но ни адрес, ни ключ никуда не уходят. Адреса http://bolvanka/v1 даже не существует.
  • dangerouslyAllowBrowser: true нужен, потому что тест идёт в браузере. Без этого флага SDK в браузере не работает: там ключ видит любой, кто открыл страницу. У Болванки ключ 'bolvanka', раскрывать нечего.
  • seen это список всех запросов, которые код отправил модели, по порядку. По нему тест проверяет, что ушло: сколько было запросов, что лежало в разговоре, какие были аргументы.

Сценарий ходов

Сценарий это список ходов. Вот сценарий для вопроса о буклетах:

import { lastUserIncludes, toolResultIncludes, type Turn } from './bolvanka';

export const booklets: Turn[] = [
  {
    calls: [{ name: 'price', args: { item: 'буклеты', copies: 200 } }],
    when: lastUserIncludes('буклет'),
  },
  { say: 'Двести буклетов стоят 7000 ₽.', when: toolResultIncludes('"total":7000') },
];

Ход это одна реплика Болванки. У хода пять полей, все необязательные:

  • say: текст ответа;
  • calls: вызовы инструментов, каждый { name, args }; id вызова Болванка выдаёт сама;
  • when: условие, при котором ход можно сыграть;
  • repeat: если true, ход можно играть сколько угодно раз;
  • finishReason: причина конца ответа, если нужна особая, например length, когда ответ оборвался на лимите.

Условия готовые:

  • lastUserIncludes(fragment): последнее сообщение пользователя содержит фрагмент;
  • toolResultIncludes(fragment): результат инструмента, пришедший после последнего ответа модели, содержит фрагмент;
  • systemIncludes(fragment): системный промпт содержит фрагмент;
  • always: подходит к любому разговору; ход без when ведёт себя так же.

Правило выбора одно: Болванка берёт первый ещё не сыгранный ход, чьё условие подходит к разговору. Ход с repeat: true сыгранным не становится.

Пройдём вопрос «Сколько стоят 200 буклетов?» по шагам:

  1. Запрос 1: системная инструкция и вопрос. Первый ход не сыгран, и в последнем сообщении пользователя есть «буклет». Болванка отвечает вызовом price с аргументами { item: 'буклеты', copies: 200 } и выдаёт ему id call_001.
  2. Приёмщик исполняет price. Результат {"item":"буклеты","copies":200,"total":7000} ложится в разговор.
  3. Запрос 2: инструкция, вопрос, вызов и результат. Первый ход уже сыгран. Второй ждёт "total":7000 в результате инструмента, и результат это содержит. Болванка отвечает текстом.
  4. Вызовов в ответе нет, и приёмщик возвращает «Двести буклетов стоят 7000 ₽.»

В model.seen после этого два запроса. Во втором лежит заявка price с id call_001: так тест видит, что приёмщик положил ответ модели в разговор, а не потерял его.

Ход не найден

Спроси приёмщика с этим сценарием про визитки. Ни одно условие не подходит: слова «буклет» в вопросе нет, результатов инструментов нет. Болванка отвечает ошибкой 400, и SDK бросает исключение:

BadRequestError: 400 ход не найден: ожидали последнее сообщение пользователя содержит «буклет»; ответ инструмента содержит «"total":7000»; пришло user: Сколько стоят 500 визиток?

В сообщении две половины. После «ожидали» перечислены условия всех ходов, которые ещё можно сыграть. После «пришло» последнее сообщение разговора. Сразу видно, какой ход ты забыл или какое условие не совпало.

Почему 400, а не 500? SDK openai по умолчанию повторяет запрос дважды, если сервер ответил ошибкой 5xx. С кодом 500 ошибка сценария пришла бы трижды и с паузами. На 400 SDK не повторяет, и ты видишь ошибку сразу.

«Ход не найден» это хорошая новость: сценарий не знает ответа и честно об этом говорит. Хуже, когда условие слишком широкое и ход подходит к вопросу, для которого его не писали.

Корректура

Ирина Львовна берёт распечатку. Ты запустил шаблон на Болванке со своим вопросом:

pnpm hello "Сколько стоят 200 буклетов?"
Клиент: Сколько стоят 200 буклетов?
Приёмщик (bolvanka): Пятьсот визиток стоят 4500 ₽.
Токены: 99 на входе, 30 на выходе
Цена запуска: $0, это Болванка. С MODEL=deepseek здесь будет цена в долларах.

Оригинал здесь сценарий шаблона src/scenario.ts. Ход с вызовом price в нём ждёт любой вопрос со словом «Сколько». Болванка не читает смысл вопроса: она проверяет условие и играет ход. Слово «Сколько» в вопросе есть, значит, сыгран ход с визитками, а за ним ответ про визитки.

Ловит это узкое условие: не шире вопросов, на которые ход отвечает. Условие lastUserIncludes('визиток') к буклетам не подойдёт, и Болванка скажет «ход не найден» вместо того, чтобы молча ответить не на тот вопрос. Хороший сценарий падает громко.

Под капотом

Сан Саныч тем временем перевернул свой листок и считает на обороте.

Болванка считает токены грубо: слово или знак препинания это один токен, плюс 4 на каждое сообщение. Для «Сколько стоят 500 визиток?» выходит так:

ЧтоСоставТокены
запрос 1, входинструкция 14 + 4, вопрос 5 + 427
запрос 1, выходвызов price: имя 1, аргументы 15, плюс 420
запрос 2, входвсё из запроса 1 (27), вызов (20), результат price 21 + 472
запрос 2, выход«Пятьсот визиток стоят 4500 ₽.» 6 + 410

На входе 27 + 72 = 99, на выходе 20 + 10 = 30. Посмотри на второй запрос: в нём заново лежит всё из первого. Инструкцию и вопрос ты оплачиваешь дважды. Вот почему длинный спор из второго урока дорожает с каждым шагом.

Настоящий токенизатор режет текст иначе, и DeepSeek насчитает другие числа. Как режет настоящий, разберёшь в шестом уроке. Болванке точность не нужна: ей нужно, чтобы числа были одни и те же при каждом прогоне и чтобы цену можно было посчитать в тесте.

На веру и на сверку

Один правильный ответ доказывает один правильный ответ. Поставщик может обновить модель под тем же именем: у DeepSeek имя deepseek-flash сейчас означает версию DeepSeek-V4.1-Flash-1017, и старое имя deepseek-v4-flash обслуживает она же. Завтра модель ответит другими словами, тест Лёвы, который сверяет текст, покраснеет, и никто не скажет, сломался код или поменялась модель.

Приём разделяет два вопроса. «Правильно ли работает мой код?» проверяет тест на Болванке: детерминированно, бесплатно, на каждый коммит. «Хорошо ли отвечает модель?» проверяют эвалы на наборе вопросов, это модуль AG13. А запуск MODEL=deepseek pnpm hello у себя это быстрая проверка, что тот же код разговаривает с настоящей моделью.

Тот же код у себя

MODEL=deepseek pnpm hello зовёт ту же функцию answer, только с клиентом DeepSeek. Отличается то, что зависит от модели: токены считает DeepSeek, текст ответа от запуска к запуску разный, цена настоящая. Путь по коду тот же: запрос, заявка price, исполнение, результат, ответ.

Отсюда правило поиска ошибок. Тест на Болванке зелёный, а у себя ответ неверный? Смотри на модель и на инструкцию, а не на цикл. Тест на Болванке красный? Модель тут ни при чём: ошибка в твоём коде или в сценарии.

Разминка

Теперь сценарий пишешь ты. Приёмщик и Болванка даны, их менять нельзя, правишь только src/scenario.ts. Тест задаст приёмщику вопросы: клиент поздоровается, потом поздоровается снова, спросит цену 500 визиток и спросит про погоду. На погоду Болванка должна сказать «ход не найден».

Практика

Глубже в архиве

Болванка курса это порт sint/dummy.py из курса бэкенда. В уроке «Свой мини-агент: цикл tool use» на Python собран цикл агента целиком: лимиты, политика инструментов, журнал, и всё это проверяет та же Болванка по сценариям.

Дальше

Сан Саныч складывает листок и уходит в цех. На его место садится Вера Андреевна и кладёт на стол другой лист, из блокнота заказов, с пронумерованными строками.

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