Запустіть флоу й прочитайте відповідь

Запуск називає код операції, передає флоу його вхід і, коли це потрібно, клієнта, для якого він виконується, і контекст виклику. Slen виконує флоу, прив’язаний до коду, і відповідає виконанням. Ця сторінка показує, що входить у виклик і що повертається; найкоротший шлях до першої відповіді — стаття Швидкий старт.

Надіслати запит

use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

$execution = $slen->operations()->execute(
    'generate_email',
    ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email to Ada.']]],
    new ExecuteOptions(customer: 'user_8421', context: ['plan' => 'pro'], idempotencyKey: 'order-57:email'),
);

• Перший аргумент — код операції. Його прив’язують до флоу в налаштуваннях флоу — як, каже стаття AI-флоу.

• Другий аргумент — вхід флоу, який його вузли читають під input. Це об’єкт, і порожній об’єкт допустимий. Флоу з вузлом AI-модель потрібен непорожній input.messages, коли він доходить до цього вузла. Без них виконання закінчується з кодом invalid_flow_input.

• Клієнт називає вашого користувача, для якого виконується запуск, — нижче.

• Ключ ідемпотентності називає одиницю роботи. Чим відповідають на повтор під ним, каже стаття Ключі ідемпотентності.

Клієнт і контекст

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

• Тип кредитів називає рахунок клієнта, який платить. SDK надсилає його як context.credit_type; без нього це рахунок default.

• Контекст несе все інше, що флоу має знати й не отримує у вході: тариф вашого клієнта, регіон запиту. Це плаский об’єкт до 64 значень. Значення — рядок, число, булеве значення або null, а весь контекст — не більше 16 384 байт у JSON.

• Вузли флоу читають значення контексту за його шляхом, context.<name>. Вузол Умова може розгалужуватися за context.plan.

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

Контекст, чий user_id називає не того клієнта, якого ви передаєте, порожній клієнт і порожній тип кредитів відхиляються до надсилання запиту, з кодом invalid_request. Запит для заблокованого клієнта відхиляється з customer_blocked, і нічого не виконується.

Прочитати відповідь

echo match (true) {
    $execution->isCompleted() => $execution->output['content'],
    $execution->isRejected() => "Refused: {$execution->errorCode} — {$execution->errorMessage}",
    $execution->isPending() => "Not over yet: {$execution->status->value}. Read it again in {$execution->retryAfterSeconds} s.",
    default => "Did not complete: {$execution->status->value}, {$execution->errorCode}",
}, PHP_EOL;

Виклик повертає виконання. Його status каже, чим закінчився запит або що він ще не закінчився, — кожен статус перелічує розділ Що каже відповідь.

• cost.actual приходить після відповіді. Розрахунок за виклики моделей виконання йде у фоні, коли воно закінчується, тому синхронна відповідь несе null, а пізніше читання — читання статусу, повтор ключа — несе суму.

• За відповідь із кешу заплатив виклик, який її отримав. cost.actual лишається null, якщо флоу не викликав модель окрім цього.

• Після відмови cost.estimated — не витрата. Виконання зі статусом rejected несе оцінку відхиленого виклику — витрату, якій відмова запобігла, — або null, коли відмова не назвала оцінки.

Відмова і збій

• Флоу, який відмовляє, відповідає як будь-який інший: вузол Відхилити запит закінчує виконання зі статусом rejected, із кодом і повідомленням, які дав йому автор. Виклик повертає виконання й нічого не кидає. isRejected() відрізняє таку відповідь від завершеної.

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

• Помилка, яка не є відмовою, — у вході немає messages, провайдер упав, а флоу цього не спрямовує, — теж кидається. Виконання закривається зі статусом failed або uncertain, коли відповідь провайдера втрачено.

Якщо прочитати таке виконання пізніше — читанням статусу, очікуванням, повтором ключа, — воно повернеться відповіддю, зі своїм статусом і error_code, а не помилкою.

Як перехопити відмову платформи в обох її формах, показує стаття Коли витрату відхилено, а будь-яку іншу помилку SDK — стаття Обробка помилок.

Коли відповідь не остаточна

• На флоу, який зупинився на вузлі, що чекає, відповідають 202 і статусом waiting. Виклик повертається без помилки, а результат читають пізніше — Асинхронні запуски й очікування.

• Флоу, який виконується довше за тайм-аут клієнта, не виконується двічі. SDK надсилає запит ще раз під тим самим ключем, і відповідь — виконання як є: running, поки воно триває, і його результат, коли воно закінчилося.

Що читати далі

• Ключі ідемпотентності — чим відповідають на повтор запиту.

• Асинхронні запуски й очікування — запустіть флоу у фоні й дочекайтеся його результату.

• Клієнти та кредити — створіть клієнта, якого називає запуск, і поповніть його кредити.

• Операції — той самий запит через HTTP.