Пару недель назад мы с командой пытались разобраться, почему наш 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:
- proceed — можно работать на primary
- degrade — primary reachable, но с проблемами, лучше работать в режиме read-only
- stop — endpoint недоступен, сессию лучше не запускать
Это резко снижает неопределённость в момент старта работы и помогает наглядно видеть, где мы сейчас.
Пример из 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.
Где это полезно, а где — нет
Кому стоит попробовать:
- командам, которые работают с AI-агентами в режиме реального времени и не хотят тратить pairing hour на инфраструктурные баги;
- тем, у кого есть fallback-модели и динамическое переключение между endpoint’ами;
- если у вас есть бесплатный слой (например, MonkeyCode free tier) — отличный low-risk способ протестировать preflight probe.
Ограничения:
- probe — это моментальный снимок, он не гарантирует, что endpoint не упадёт через час;
- shape check ловит лишь синтаксис вызова, не проверяет семантику;
- для workloads с SLA и строгими ограничениями нужна дополнительная система алертов поверх ledger.
Итог
Писать политику в markdown для AI-агента — это как писать контракт с самим собой на песке. Лучше сделать явное preflight решение — скрипт, который скажет тебе в момент старта, на что можно рассчитывать. Это уменьшит “тайные” retry, уберёт двойные циклы и даст прозрачность выбора endpoint’а.
Для нас preflight probe стал не просто скриптом, а точкой контроля и коммуникации внутри команды. Если у вас есть возможность — попробуйте сделать ladder и вести ledger. В крайнем случае, это даст понимание, что происходит “под капотом”, вместо того чтобы надеяться на vibes.
Попробуй сам: Cursor — AI-редактор для разработчиков.