Удалили политику агента и написали preflight probe — как пара часов изменили подход к retry

#ai coding#agentic workflows#retry#preflight probe

Пару недель назад мы с командой пытались разобраться, почему наш AI-агент с политикой, описанной в AGENTS.md, то и дело ведёт себя непредсказуемо. В итоге за час парного программирования удалили почти всю политику из документа и написали скрипт preflight probe, который запускается до сессии, а не во время неё. Вот что из этого вышло.

Политика в markdown — круто, но бесполезно

Сначала показалось логичным держать правила поведения агента в AGENTS.md: retry-стратегии, предпочтения моделей, запреты на использование некоторых эндпоинтов. Политика — это как договор с самим собой, типа “не трогать /v2, не ретраить при schema errors, бэкапиться на fallback”.

Но senior-инженер взглянула на этот документ и спросила:
“Что из этого реально гарантируется? Что из этого принудительно выполняется?”

Ответ — ничего. Там просто описание намерений. А модели — это вероятностные существа, им всё равно, что написано в markdown. Если retry-правила не в коде, а в документе, они не работают.

Я сам много раз попадал в эту ловушку: документация и политика — это не контрольные конструкции. Если что-то должно сработать всегда, нужно явно писать код, а не надеяться, что AI “понял”.

Retry loops и двойная магия

Первые мысли — добавить retry прямо в обёртку, которая собирает промты. Сделали. Всё вроде хорошо, но через час заметили, что latency внезапно растёт, а в логах одна логическая операция превращается в 4-5 запросов.

Двойные retry loops — классическая ошибка. Они не только удваивают количество запросов, но и делают метрики непонятными. У нас получилась “толстая хвостовая” latency distribution — редкая, но очень длинная задержка, которую сложно отследить.

Из этого вывода:
retry loop должен быть в одном месте и отвечать за свои собственные записи в ledger.

Иначе теряется прозрачность, и вы не понимаете, сколько реально запросов ушло.

Очереди и backoff — не для отладки в паре

Третья идея — поставить запросы в очередь с экспоненциальным backoff. С точки зрения стабильности сервиса — классика. Но senior сразу отмела её. Почему?

Наблюдаемость.

В паре вы хотите видеть, что endpoint прямо сейчас отвечает или нет. Очередь скрывает эту проблему — “endpoint struggling” превращается в “очередь растёт”. Это хуже, чем ничего, когда надо быстро понять, что не так.

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

Preflight probe — проверяем перед стартом

В итоге мы остановились на скрипте, который запускается до сессии. Он пробегает по списку endpoint’ов (мы зовём его ladder), проверяя reachability и корректность ответов (в том числе shape tool calls), и записывает результаты в ledger — JSONL-файл.

По итогам скрипт выдаёт verdict:

Это резко снижает неопределённость в момент старта работы и помогает наглядно видеть, где мы сейчас.

Пример из preflight.mjs

import { appendFile } from "node:fs/promises";

const LEDGER = new URL("./preflight-ledger.jsonl", import.meta.url);

const LADDER = [
  { id: "primary",  url: process.env.MC_URL_A, model: process.env.MC_MODEL_A },
  { id: "fallback", url: process.env.MC_URL_B, model: process.env.MC_MODEL_B },
];

async function record(row) {
  await appendFile(LEDGER, JSON.stringify({ at: new Date().toISOString(), ...row }) + "\n");
}

async function probeReach(ep, timeoutMs = 15000) {
  const ac = new AbortController();
  const t = setTimeout(() => ac.abort(), timeoutMs);
  const started = performance.now();
  try {
    const res = await fetch(`${ep.url}/models`, { signal: ac.signal });
    return { ok: res.ok, status: res.status, ttfbMs: Math.round(performance.now() - started) };
  } catch (err) {
    return { ok: false, status: 0, error: String(err.name) };
  } finally {
    clearTimeout(t);
  }
}

async function probeToolShape(ep, timeoutMs = 20000) {
  const ac = new AbortController();
  const t = setTimeout(() => ac.abort(), timeoutMs);
  const started = performance.now();
  try {
    const res = await fetch(`${ep.url}/chat/completions`, {
      method: "POST",
      signal: ac.signal,
      headers: {
        "content-type": "application/json",
        authorization: `Bearer ${process.env.MC_KEY}`,
      },
      body: JSON.stringify({
        model: ep.model,
        messages: [{ role: "user", content: "Call the ping tool with id 1." }],
        tools: [{
          type: "function",
          function: {
            name: "ping",
            parameters: { type: "object", properties: { id: { type: "number" } }, required: ["id"] },
          },
        }],
      }),
    });
    const body = await res.json();
    const call = body?.choices?.[0]?.message?.tool_calls?.[0];
    let argsOk = false;
    try { argsOk = typeof JSON.parse(call.function.arguments).id === "number"; } catch {}
    return { ok: Boolean(call) && argsOk, ttftMs: Math.round(performance.now() - started) };
  } catch (err) {
    return { ok: false, error: String(err.name) };
  } finally {
    clearTimeout(t);
  }
}

(async () => {
  const verdicts = [];
  for (const ep of LADDER.filter((e) => e.url && e.model)) {
    const reach = await probeReach(ep);
    await record({ probe: "reach", endpoint: ep.id, ...reach });
    if (!reach.ok) { verdicts.push({ id: ep.id, verdict: "stop" }); continue; }

    const shape = await probeToolShape(ep);
    await record({ probe: "tool_shape", endpoint: ep.id, ...shape });
    verdicts.push({ id: ep.id, verdict: shape.ok ? "proceed" : "degrade" });
  }

  const chosen = verdicts.find((v) => v.verdict === "proceed");
  console.log(JSON.stringify({ chosen: chosen?.id ?? null, verdicts }, null, 2));
  process.exit(chosen ? 0 : 1);
})();

Немного о vibe coding и агентных workflow

Этот preflight probe — классический пример vibe coding: минимум движка в рантайме, максимум внешних проверок и прозрачных данных. Вся логика принятия решения вынесена вне основного кода агента. Это снижает когнитивную нагрузку и повышает predictability.

Agentic workflows страдают от того, что многие решения завязаны на непредсказуемом поведении AI и сетевых условий. Preflight probe даёт возможность взять контроль над выбором endpoint’а и состоянием системы до того, как начнётся сессия. В итоге можно не гадать, а иметь чёткий snapshot.

Где это полезно, а где — нет

Кому стоит попробовать:

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

Итог

Писать политику в markdown для AI-агента — это как писать контракт с самим собой на песке. Лучше сделать явное preflight решение — скрипт, который скажет тебе в момент старта, на что можно рассчитывать. Это уменьшит “тайные” retry, уберёт двойные циклы и даст прозрачность выбора endpoint’а.

Для нас preflight probe стал не просто скриптом, а точкой контроля и коммуникации внутри команды. Если у вас есть возможность — попробуйте сделать ladder и вести ledger. В крайнем случае, это даст понимание, что происходит “под капотом”, вместо того чтобы надеяться на vibes.


Попробуй сам: Cursor — AI-редактор для разработчиков.


Источник: https://dev.to/appjs_7055/the-pairing-hour-where-we-deleted-the-agent-policy-doc-and-wrote-a-preflight-probe-instead-2ndi