Laravel AI v0.11.0 пропонує розширені можливості для відстеження роботи агентів: тепер кожний запуск отримує єдиний correlation ID та набір подій життєвого циклу, що спрацьовують під час кожного запиту до провайдера чи виклику інструменту. Раніше запуск, який потребував п'яти ітерацій для виконання завдань, виглядав ідентично до запуску з одним запитом, а помилки на рівні gateway могли залишатися непоміченими. Реліз відбувся 19 серпня 2026 року та містить 36 закритих pull requests від 12 нових контриб'юторів.
- Єдиний invocation id для всього циклу роботи, включно зі спробами failover
- Нові події `StartingStep`, `StepCompleted`, `StepFailed`, `ToolFailed` та `AgentFailed` із точним вимірюванням часу
- Підтримка хостингового пошуку інструментів (hosted tool search) для OpenAI та Anthropic через обгортку `ToolSearch`
- Failover тепер спрацьовує при помилках з'єднання, додаткових кодах помилок та лімітах використання Anthropic
- Веб-пошук і пошук у файлах для xAI, транскрипція для Groq та OpenAI-сумісних провайдерів
- Помилки стрімів (stream errors) тепер викликають exceptions замість мовчазного завершення
- Новий assertion для тестів — `assertPromptedTimes()`
# Що нового
# Трейсинг повного циклу роботи агента
Завдяки внеску @pushpak1300 було повністю перероблено систему звітів про роботу агента.
Раніше `streamPrompt()` створював ID на рівні запуску, але `prompt()` цього не робив, через що синхронні middleware отримували `null`. Тепер `prompt()` генерує ID одразу, а провайдер використовує вже існуюче значення (#871).
Контекст `RunContext` тепер відповідає за ідентифікацію запуску та запуск подій, замінюючи старі callback-функції. Раніше ID виклику інструменту зберігався в одній властивості, що спричиняло помилки при вкладених викликах. Тепер ID створюється всередині `executeTool()`, а інструменти можуть отримати його через `Request::toolInvocationId()` (#872).
Події `StartingStep`, `StepCompleted` та `StepFailed` тепер працюють як для синхронних, так і для стрімінгових запитів (#873). `StartingStep` містить історію повідомлень та параметри кроку, а події завершення фіксують час виконання у мілісекундах (аналогічно до `QueryExecuted::$time`).
Раніше помилки в обробниках інструментів не фіксувалися належним чином. Тепер подія `ToolFailed` звітує про такі випадки, зберігаючи відповідний ID виклику (#874). На рівні всього запуску `AgentFailed` повідомляє про критичну помилку лише після того, як вичерпано всі можливості failover у ланцюжку провайдерів (#876).
Також реалізовано зв'язок між батьківськими та дочірніми агентами через `parentInvocationId` та `parentToolInvocationId` (#875). Це працює для будь-яких інструментів, що викликають агентів, але не поширюється на завдання у чергах через `promptOnQueue()`.
# Хостинговий пошук інструментів
Раніше всі доступні агенту інструменти надсилалися провайдеру з кожним запитом, що збільшувало витрати токенів. @behzadsp додав обгортку `ToolSearch` (#697), яка дозволяє OpenAI та Anthropic завантажувати інструменти за запитом:
public function tools(): iterable
{
return [
new WeatherTool,
new ToolSearch(tools: [new SearchInvoices, new RefundOrder]),
];
}Це не потребує змін у самих інструментах. Обгортка автоматично конвертується у відповідні типи для OpenAI та Anthropic. Для Anthropic також можна вказати стратегію пошуку (`regex` або `bm25`):
new ToolSearch(tools: [new SearchInvoices], strategy: 'bm25')Якщо провайдер не підтримує такий пошук, система видасть помилку ще до надсилання запиту. Оскільки хостинговий пошук OpenAI потребує збереження відповідей, використання `ToolSearch` із параметром `store=false` викличе виключення.
# Розширений Failover
Система failover тепер спрацьовує у трьох нових сценаріях, виявлених на реальних проєктах.
По-перше, виправлено обробку `ConnectionException` (наприклад, коли локальний Ollama не запущений або хост недоступний). Тепер такі помилки конвертуються у `ProviderConnectionException` і дозволяють переключитися на інший провайдер (#781).
По-друге, розширено список статусів, що вважаються перевантаженням провайдера: до `503` додалися `502`, `504`, `520`, `522` та `524`. Це охоплює помилки Cloudflare та тайм-аути шлюзів (#810, #884).
По-третє, додано підтримку лімітів витрат Anthropic. Раніше помилка 400 при досягненні spend cap не розпізнавалася як критична для failover. Додавання фрази `usage limit` до списку паттернів вирішило цю проблему (#864).
# Оновлення провайдерів
- xAI: додано веб-пошук (#857) та пошук у файлах (#894)
- Транскрипція аудіо: тепер доступна для Groq та OpenAI-сумісних провайдерів
- OpenRouter: додано підтримку інструменту веб-запитів (#889)
- Anthropic: цитати веб-пошуку тепер коректно відображаються у `$response->meta->citations` (тільки для синхронних запитів)
- Gemini: модель за замовчуванням оновлена до `gemini-3.7-flash` (#887)
# Допоміжні функції для тестування
Додано `assertPromptedTimes()` для перевірки кількості запитів, аналогічно до тестування черг чи сповіщень у Laravel (#891):
SalesCoach::assertPromptedTimes(3);Тестові фейки для генерації медіафайлів (зображень, аудіо тощо) тепер коректно виконують callback-функцію `then(...)`, що спрощує перевірку результатів у тестах (#797).
# Інші виправлення
- Покращено підрахунок токенів у стрімах та виправлено облік кешованих токенів для OpenAI та DeepSeek.
- Оптимізовано роботу з історією діалогів та виправлено обробку невідомих локальних інструментів.
- Додано обробку специфічних відповідей Mistral та Anthropic, а також очищення markdown-розмітки у структурованих відповідях OpenAI.
- Виправлено роботу з вкладеннями S3 та документами в Anthropic.
Примітки щодо оновлення
Помилки всередині стріму (HTTP 200 з об'єктом `error` у payload) тепер викликають `StreamErrorException`. Раніше це призводило до отримання неповного тексту без повідомлення про збій. Ця помилка навмисно не ініціює failover, оскільки технічно запит отримав статус 200 (#870).
У конструктори подій `AgentFailedOver` та `ToolInvoked` додано обов'язкові аргументи. Це важливо лише для тих, хто створює ці події вручну.
Модель Gemini за замовчуванням тепер — `gemini-3.7-flash`. Якщо вам потрібна попередня версія, вкажіть її явно в конфігурації.
Оновитися можна командою `composer update laravel/ai`. Документація доступна на офіційному сайті Laravel.
Посилання