---
title: "Новинний пайплайн на Laravel AI SDK: агенти, structured output і пастки, про які не попереджають"
url: https://laravelukraine.com/blog/novinnii-paiplain-na-laravel-ai-sdk-agenti-structured-output-i-pastki-pro-iaki-ne-poperedzaiut
date: 2026-11-19
source: https://dev.to/divoto/building-a-news-pipeline-with-the-laravel-ai-sdk-agents-structured-output-and-the-pitfalls-nobody-49la
---

# Новинний пайплайн на Laravel AI SDK: агенти, structured output і пастки, про які не попереджають

Це переказ статті [Івайло Ніколова](https://dev.to/divoto/building-a-news-pipeline-with-the-laravel-ai-sdk-agents-structured-output-and-the-pitfalls-nobody-49la) (dev.to, 17 листопада 2026) про новинний сервіс NewSumm. Він читає новини сотень видань, об'єднує статті про ту саму подію в одну історію і пише короткий підсумок: у чому видання сходяться і де розходяться. У звичайний день це десятки тисяч статей.

Увесь пайплайн працює на [Laravel AI SDK](https://github.com/laravel/ai) (`laravel/ai`): ембединги для кожної статті та агенти, які підсумовують історії, описують кут подачі кожного видання і витягують людей і місця, про які йдеться. Нижче - Laravel-частина: як організовано код, що SDK дає безкоштовно, і три збої, що коштували команді реального часу, бо жоден тест їх не бачив. Математику кластеризації автор розбирає в окремому пості, тут лишаємося в PHP.

Код спрощено порівняно з реальними класами: промпти, моделі та пороги прибрано навмисно, переноситься саме структура.

### 1. Форма пайплайна

Кожен крок - завдання в черзі:

1. **Fetch** - забрати фіди і зберегти нові статті.
2. **Embed** - один вектор на статтю із заголовка та опису.
3. **Cluster** - згрупувати статті в історії за подібністю векторів у Postgres з pgvector.
4. **Summarise** - підсумувати кожну історію, до якої приєдналося більше однієї статті.

Мовну модель викликає лише крок 4 і лише для історій з кількох статей. У дводенній вибірці з 51 842 статей історій із двома і більше статтями було 4 748, тобто **9,2%** від кількості статей. Більша частина рішення про вартість ухвалюється ще до того, як запрацює будь-який агент: надсилайте моделі *історії*, а не *статті*.

### 2. Ембединги: пакетами, і з перевіркою входу

API ембедингів у SDK - один рядок:

```php
use Laravel\Ai\Embeddings;

$response = Embeddings::for($texts)->generate();

$vectors = $response->embeddings; // по масиву float на кожен вхід, у тому ж порядку
```

Ембединги генеруються пакетами по 50, тож один HTTP-запит покриває 50 статей. Проблемою був не виклик, а вхідні дані.

Дані з фідів брудні, і один поганий рядок змушує провайдера повернути **400 на весь пакет**. Автор натрапив на три випадки:

- **Задовгий текст.** Деякі фіди кладуть в опис усю статтю. Текст обрізають із запасом до ліміту токенів провайдера, причому нижче, ніж підказує звичне правило «чотири символи на токен»: щільні нелатинські писемності витрачають значно більше токенів на символ.
- **Порожній текст.** Ні заголовка, ні опису - пропускаємо.
- **Виглядає порожнім, але ні.** Заголовки, що складаються лише з нерозривного пробілу або пробілу нульової ширини (zero-width space). `trim()` і `filled()` їх пропускають, провайдер бачить порожній рядок і відхиляє пакет.

```php
private function isBlank(string $text): bool
{
  return $text === '' || preg_match('/^[\p{C}\p{Z}]+$/u', $text) === 1;
}
```

Третій випадок ударив найболючіше. Відхилений пакет лишав свої статті позначеними як необроблені, тож їх повторювали на кожному запуску, і завдання (яке тоді йшло від найстаріших) ніколи не просувалося далі. Свіжі статті перестали отримувати ембединги, отже нічого не кластеризувалося і нічого не підсумовувалося. Сайт просто перестав показувати нові історії. Виправлень два: перевіряти вхід і обробляти **спершу найновіші**, щоб одна «отруєна» стаття ніколи не затримала сьогоднішні новини.

Варто знати: у Laravel 13.43 у `Stringable` з'явилися `isBlank()` і `isNotBlank()`, але цю проблему вони не розв'язують. Метод спирається на хелпер `blank()`, тобто на звичайний `trim()`, і тести фреймворку прямо фіксують, що `str("\u{00A0}")->isBlank()` і `str("\u{200B}")->isBlank()` повертають `false`. Для невидимих символів потрібна власна перевірка на кшталт регулярного виразу вище.

> **Порада.** Коли пакетний виклик може впасти через один елемент, позначайте елементи, які неможливо обробити, як *оброблені, без результату*, а не лишайте їх у черзі. Вічний повтор поганого входу - це повільна відмова сервісу.

### 3. Агенти - це просто класи

Агент у SDK - це клас, що реалізує `Agent` і використовує трейт `Promptable`. Інструкції живуть у методі, тож їх версіонують, рев'юють і тестують як будь-який інший код:

```php
namespace App\Ai\Agents;

use Laravel\Ai\Attributes\UseCheapestModel;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
use Stringable;

#[UseCheapestModel]
class StorySummaryAgent implements Agent
{
  use Promptable;

  public function __construct(public bool $compareOutlets = false) {}

  public function instructions(): Stringable|string
  {
    return 'You are a news editor. Summarise what these articles agree on...';
  }
}
```

Дві речі тут себе виправдали.

**`#[UseCheapestModel]`** каже SDK взяти найдешевшу текстову модель провайдера. Завдання вузькі (підсумувати, порівняти, заповнити схему), і малі моделі справляються з ними добре. Атрибут тримає назви моделей поза кодом: змінили провайдера - і всі агенти пішли слідом.

**Аргументи конструктора** передаються через `make()`, тож один агент може змінювати поведінку від виклику до виклику без другого класу:

```php
$response = StorySummaryAgent::make(compareOutlets: $story->hasEnoughSources())
  ->prompt($this->articlesPrompt($articles));
```

Коли `compareOutlets` увімкнено, і інструкції, і схема агента отримують розділ «де висвітлення відрізняється». Один клас, один файл тестів, дві поведінки.

### 4. Structured output перетворює автора на екстрактора

Вільний текст важко зберігати. Потрібні заголовок, підсумок, ключові тези, категорія з фіксованого списку, кут подачі кожного видання, люди й місця. Реалізуємо `HasStructuredOutput` і описуємо форму:

```php
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\HasStructuredOutput;

class StorySummaryAgent implements Agent, HasStructuredOutput
{
  // ...

  public function schema(JsonSchema $schema): array
  {
    return [
      'headline' => $schema->string()->required(),
      'summary' => $schema->string()->required(),
      'key_points' => $schema->array()->items($schema->string())->required(),
      'category' => $schema->string()->enum(Category::values())->required(),
      ...($this->compareOutlets ? [
        'coverage_differences' => $schema->string()->required(),
      ] : []),
    ];
  }
}
```

Відповідь читається як масив:

```php
$story->update([
  'headline' => $response['headline'],
  'summary' => $response['summary'],
  'category' => $response['category'],
]);
```

`enum` на категорії означає, що модель обирає з вашого списку, а не вигадує одного дня «Tech & Science», а наступного «Technology». Те, що повертається, однаково варто валідувати (схема обмежує форму, а не правдивість), але різновидів сміття стає значно менше.

#### Спільні правила і схема для кількох агентів

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

```php
class EntityExtractionAgent implements Agent, HasStructuredOutput
{
  use Promptable;

  public const Rules = <<<'PROMPT'
    Record who the story is about, and where it happened...
    PROMPT;

  public function schema(JsonSchema $schema): array
  {
    return self::fields($schema);
  }

  public static function fields(JsonSchema $schema): array
  {
    return ['entities' => /* people + places */];
  }
}

// У StorySummaryAgent::schema():
...EntityExtractionAgent::fields($schema),
```

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

### 5. Пастка strict-схеми

Цей збій на день вимкнув щоденний дайджест, а весь набір тестів лишався зеленим.

Режим structured output у провайдера **строгий** (strict): кожен об'єкт у схемі має містити `additionalProperties: false` і позначати всі свої властивості як обов'язкові. SDK надсилає запити в strict-режимі і сам додає `additionalProperties: false` до **кореневого** об'єкта. До **вкладених** - не додає.

Тож так працює:

```php
'key_points' => $schema->array()->items($schema->string()),
```

а так відхиляється з 400 на кожному виклику:

```php
'beats' => $schema->array()->items($schema->object([
  'title' => $schema->string()->required(),
  'text' => $schema->string()->required(),
])),
```

Виправлення - один виклик методу на кожному вкладеному об'єкті:

```php
'beats' => $schema->array()->items($schema->object([
  'title' => $schema->string()->required(),
  'text' => $schema->string()->required(),
])->withoutAdditionalProperties()),
```

Ситуацію погіршили три речі:

- **Фейки не валідують схеми.** `Agent::fake()` ніколи не звертається до провайдера, тож не може застосувати його правила. Усі тести проходили.
- **Завдання ковтало помилку.** Воно перехоплювало виняток, писало попередження в лог, пропускало категорію і публікувало *порожній* дайджест. У `failed_jobs` нічого не потрапляло, усе виглядало як тихий день без новин.
- **Лог ховав причину.** Повідомлення винятку обрізалося раніше, ніж та частина тіла відповіді, де називалося хибне поле.

Тепер тест компілює справжню схему кожного агента рівно так, як її надішле SDK, і рекурсивно її обходить:

```php
use Illuminate\JsonSchema\JsonSchemaTypeFactory;
use Laravel\Ai\ObjectSchema;

function assertStrictModeCompatible(array $schema, string $path = 'root'): void
{
  expect($schema['additionalProperties'] ?? null)
    ->toBeFalse("Object at {$path} is missing additionalProperties: false");

  expect($schema['required'] ?? [])
    ->toEqualCanonicalizing(array_keys($schema['properties'] ?? []), "Object at {$path} must mark every property required");

  foreach ($schema['properties'] ?? [] as $name => $property) {
    if (($property['type'] ?? null) === 'object') {
      assertStrictModeCompatible($property, "{$path}.{$name}");
    }

    if (($property['type'] ?? null) === 'array' && ($property['items']['type'] ?? null) === 'object') {
      assertStrictModeCompatible($property['items'], "{$path}.{$name}[]");
    }
  }
}

it('compiles a schema strict mode accepts', function (string $agent) {
  $schema = (new ObjectSchema((new $agent)->schema(new JsonSchemaTypeFactory)))->toSchema();

  assertStrictModeCompatible($schema);
})->with([
  StorySummaryAgent::class,
  EntityExtractionAgent::class,
  DailyRecapAgent::class,
]);
```

Жодного API-виклику, мілісекунди на виконання, і збірка падає щойно хтось додасть вкладений об'єкт без виправлення.

> **Увага.** Якщо завдання викликає модель у циклі і перехоплює помилки для кожного елемента, піднімайте тривогу, коли падають *усі* елементи. Усі елементи, що впали за лічені секунди, - це відхилений запит, а не невдала генерація.

### 6. Агенти в чергах: стежте за `retry_after`

Підсумки генеруються в завданнях черги, а виклик моделі може тривати довго. Якщо завдання працює довше за `retry_after` підключення черги, Laravel віддає його другому воркеру, поки перший ще працює, і ви платите за той самий підсумок двічі. У NewSumm на старті стояв стандартний `retry_after` у 90 секунд при таймаутах завдань у кілька хвилин. Поки це помітили, набралося 726 збійних завдань і чимало дубльованих викликів моделі.

Емпіричне правило: `retry_after` має бути довшим за найдовший таймаут завдання на цьому підключенні.

### 7. Скільки це коштує

Дашборди провайдерів показують, скільки ви витратили, але не показують, *який агент* це витратив. SDK запускає подію після кожного виклику з прикріпленим використанням токенів, тож слухач може записати кожен:

```php
use Laravel\Ai\Events\AgentPrompted;
use Laravel\Ai\Events\EmbeddingsGenerated;

class RecordAiUsage
{
  public function handleAgentPrompted(AgentPrompted $event): void
  {
    $usage = $event->response->usage;

    $this->record([
      'agent' => class_basename($event->prompt->agent),
      'model' => $event->prompt->model,
      'input_tokens' => $usage->promptTokens,
      'cached_input_tokens' => $usage->cacheReadInputTokens,
      'output_tokens' => $usage->completionTokens,
    ]);
  }

  public function handleEmbeddingsGenerated(EmbeddingsGenerated $event): void
  {
    $this->record([
      'agent' => 'embeddings',
      'model' => $event->model,
      'input_tokens' => $event->response->tokens,
    ]);
  }

  private function record(array $attributes): void
  {
    try {
      AiUsage::query()->create($attributes);
    } catch (Throwable $e) {
      Log::warning("Could not record AI usage: {$e->getMessage()}");
    }
  }
}
```

Автовиявлення подій у Laravel знаходить методи `handle*` за підказками типів, тож реєструвати нічого не треба. Зверніть увагу на `try`/`catch`: облік ніколи не повинен валити виклик, який він записує. Підсумок, за який уже заплачено, цінніший за рядок про його використання.

Поверх цієї таблиці працює Artisan-команда `php artisan ai:usage`, що групує токени за агентами (або за годинами з `--hourly`) і множить їх на ціни моделей із конфігурації.

### 8. Тестування з фейками і їхні межі

Для всього, що не стосується контракту з провайдером, фейки SDK чудові:

```php
it('stores the overview the agent writes', function () {
  EntityOverviewAgent::fake(fn (): array => ['overview' => "First paragraph.\n\nSecond paragraph."]);

  // ... запускаємо завдання ...

  EntityOverviewAgent::assertPrompted(fn ($prompt) => $prompt->contains('Kyiv'));
});

it('skips articles with blank titles', function () {
  Embeddings::fake();

  // ... генеруємо ембединги для пакета, де один із заголовків "\u{00A0}" ...

  Embeddings::assertGenerated(fn ($prompt) => count($prompt->inputs) === 49);
});
```

Фейки відповідають на питання «чи правильно мій код поводиться з відповіддю?». На питання «чи прийме провайдер мій запит?» вони відповісти не можуть. Для цього потрібен або контрактний тест на кшталт обходу схеми вище, або один маленький справжній виклик у запланованій smoke-перевірці. Перше в команди є, і автор шкодує, що не з'явилося раніше.

### Підсумок

Що автор радить тим, хто починає сьогодні:

- **Вирішіть, що читатиме модель, перш ніж обирати модель.** Перехід від статей до історій скоротив кількість викликів на порядок, жоден вибір моделі з цим не зрівняється.
- **Робіть агентів класами з інструкціями в коді.** Їх рев'юють, порівнюють у диффах і тестують як усе інше.
- **Використовуйте structured output для всього, що зберігаєте**, з `enum` скрізь, де відповідь береться зі списку.
- **Тестуйте схему, яку надсилаєте, а не лише відповідь, яку підробляєте.** Вкладеним об'єктам потрібен `withoutAdditionalProperties()`.
- **Перевіряйте вхід для ембедингів** на задовгий, порожній і невидимо-порожній текст і ніколи не дозволяйте одному поганому елементу назавжди заблокувати пакет.
- **Записуйте токени по кожному агенту з першого дня.** Це один слухач, і він показує, куди насправді йдуть гроші.
- **Ніколи мовчки не ковтайте помилку моделі.** Логуйте тіло відповіді і піднімайте тривогу, коли падають усі елементи.

SDK робить щасливий шлях коротким. Основна робота була в нещасливих шляхах, і саме їх варто записувати.
