# Проєктування мультиагентного конвеєра

> Агент рідко є складною частиною агентної системи. Складні — черга, бюджет, довговічний запис і незалежна перевірка. Ось що я переношу між ними.

В агентній системі агент рідко є складною частиною. Складні — черга перед ним, бюджет навколо нього, довговічний запис під ним і незалежна перевірка після нього. Я будував це кілька разів — рантайм за AI-visibility платформою, дослідницький каскад для валідації стартапів, контент-конвеєр, що чекає підтвердження людини, перш ніж опублікувати, — і саме каркас переноситься між ними.

## Чому конвеєр, а не промпт

Промпт повертає відповідь. Щоб повертати ту саму відповідь надійно й за передбачуваною ціною, потрібні стадії навколо нього: план, який можна оглянути, стан, який можна відтворити, і крок, що може відхилити результат. Це й є конвеєр — і це більша частина інженерії.

### Форма запуску

Кожен запуск проходить ті самі стадії й пише в той самий запис. Якщо дізнатися, що сталося, можна лише запустивши його знову, — запис не виконує свою роботу.

## Став повільну роботу за чергу

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

Дай кожному запуску бюджет і зупиняйся, коли його вичерпано:

```ts
interface RunBudget {
  maxSteps: number;
  maxTokens: number;
  deadline: number; // epoch ms
}

function withinBudget(spent: RunBudget, limit: RunBudget): boolean {
  return (
    spent.maxSteps <= limit.maxSteps &&
    spent.maxTokens <= limit.maxTokens &&
    Date.now() <= limit.deadline
  );
}
```

### Ретраї без дублювання

Ретраї — нормально; повторені сайд-ефекти — ні. Ключуй кожен крок так, щоб ретрай був ідемпотентним: друга спроба підтверджує першу, а не робить її знову.

## Зроби стан явним

Кожен запуск — довговічний запис, і кожен крок пише свої входи й виходи. Тоді трасування є джерелом істини, а не реконструкцією заднім числом.

| Що               | Де живе             | Чому                                   |
| ---------------- | ------------------- | -------------------------------------- |
| Метадані запуску | таблиця `runs`      | Один рядок на запуск, статус і бюджет  |
| Входи/виходи     | таблиця `steps`     | Входи, виходи, час кожного кроку       |
| Артефакти        | об'єктне сховище    | Великі дані тримаємо поза БД           |

## Виробник не оцінює себе сам

Агент, що переглядає власний вихід, не каже тобі нічого. Конвеєри, яким я довіряю, мають незалежний прохід: верифікатор, що не виробляв те, що перевіряє; рев'ю, яке автор не може затвердити. Обмеж його бюджетом, щоб не зациклився, а коли щось лишається відкритим після вичерпання бюджету, віддай це людині, а не познач як зроблене.

## Спостережність

Якщо ти не бачиш, чому агент зробив те, що зробив, ти не можеш запускати його в продакшні. Span на кожен крок перетворює запуск на трасування, яке читаєш згори донизу, тож «вихід неправильний» стає «планувальник обрав не той інструмент на кроці чотири», а це вже баг, який можна полагодити.

## Що переноситься

Ніщо з цього не залежить від фреймворку чи моделі. Це та сама дисципліна — чи агенти підсумовують документ, чи вирішують, готова сторінка до публікації: зроби роботу спостережною й зроби так, щоб її затверджував хтось, окрім виробника.