Інструменти
Інструмент — це названа дія, яку може викликати ШІ, з типізованими вхідними даними — наприкладsend_email(to, subject, body). Інструменти оголошуються в tools.ts навички, а для інструментів, які служить ваш додаток, підтримуються маршрутом HTTP в одному з ваших компонентів. Ця сторінка є джерелом істини для контракту інструменту; Навички описують, де живе tools.ts.
Оголошення інструменту
Кожен запис уtools.ts має безпечне для провайдера name, дружелюбне displayName, description, Zod схему input та target, який вказує, що викликає Kazzle.
Цілі
target — це повторно використовувана адреса для інструменту або кнопки обов’язкової дії. Прямий виклик інструменту ШІ та клік кнопки можуть використовувати той самий об’єкт цілі, тому обидва запускають той самий код.
HTTP цілі використовують одні й ті ж поля запиту:
body: '${input}'.
Посилання
Kazzle розв’язує посилання в полях HTTP ціліquery, headers, body та url перед відправленням:
${input}— усі вхідні дані інструменту або усі вхідні дані кнопки.${input.path}— вкладене значення з вхідних даних.${env.NAME}— названа змінна середовища з оголошеноїenv.collection+env.environmentкомпонента додатку, якому належить.
$${input.name}, коли вам потрібен літеральний текст ${input.name}.
Запит обробника
Для ціліapp додайте відповідний маршрут у компонент цілі. З body: '${input}', Kazzle відправляє типізовані вхідні дані як тіло JSON:
app також отримують:
Цілі додатку не можуть встановлювати
Authorization через headers; Kazzle володіє цим заголовком. Прочитайте контекст за допомогою toolContext(req) з @kazzle/app/tools, коли обробник повинен розгалужуватися між потоком та Tools API.
Інструмент, оголошений без відповідного маршруту, не робить нічого корисного — додайте обидва разом. tools.json не підтримується; компілятор додатку не спрацює, якщо його знайде.
Відповідь обробника
Повертайте простий текст або JSON з до трьох каналів:content— простий результат, який читає ШІ (передається моделі). Обов’язково.markdown— опціонально. Коротке резюме з багатим текстом, відтворене в карточці інструменту (react-markdown; сирий HTML екранується). Добре для речення, невеликого списку, вбудованого посилання. Голий відносний шлях відтворюється як мертвий попередньо відформатований текст — посилання повинні бути абсолютними.embedUrl— опціонально. Абсолютна URL, яку служить ваш додаток; карточка відтворює її в пісочниці iframe. Це те, як ви показуєте справжній, повноширокий інтерфейс — екран підключення, панель керування, діаграму. Ваш додаток розміщує та володіє сторінкою, тому вона може бути повністю інтерактивною проти вашого власного бекенду, файлів cookie та OAuth. Нічого не записується на диск.
embedUrl переважає markdown, коли обидва встановлені. Завжди зберігайте змістовний content — це те, що читає ШІ.
Обов’язкова дія
Інструмент додатку може призупинити потік, коли йому потрібна дія користувача (або пристрою). Повертайтеtype: 'action_required' з назвою карточки та кнопками. Дійсно лише коли toolContext(req).source === 'thread' — через Tools API (source: 'api'), замість цього повертайте звичайну помилку домену.
/chat/resume після натискання кнопки. Відповідні клієнти бачать кнопки автора; невідповідні клієнти все ще бачать Пропустити/Скасувати плюс «Продовжити на ». Кнопка без target подає свої input як результат інструменту. Кнопка з цільовою адресою спочатку запускає цю ціль, потім використовує результат цілі як результат інструменту.
Багатий інтерфейс — вбудуйте сторінку, розміщену додатком
Коли результат інструменту є візуальним або інтерактивним (екран підключення, діаграма, панель керування резюме), служіть сторінку з одного з ваших компонентів та повертайте її абсолютну URL якembedUrl. Побудуйте URL з введеної URL компонента — ніколи не відносний шлях.
embedUrl над випусканням рядків HTML: ваш додаток уже служить сторінкам, інтерфейс залишається інтерактивним та версіонованим з вашим кодом, і жодні артефакти за виклик не записуються ніде.