Skip to main content

Інструменти

Інструмент — це названа дія, яку може викликати ШІ, з типізованими вхідними даними — наприклад send_email(to, subject, body). Інструменти оголошуються в tools.ts навички, а для інструментів, які служить ваш додаток, підтримуються маршрутом HTTP в одному з ваших компонентів. Ця сторінка є джерелом істини для контракту інструменту; Навички описують, де живе tools.ts.

Оголошення інструменту

Кожен запис у tools.ts має безпечне для провайдера name, дружелюбне displayName, description, Zod схему input та target, який вказує, що викликає Kazzle.

Цілі

target — це повторно використовувана адреса для інструменту або кнопки обов’язкової дії. Прямий виклик інструменту ШІ та клік кнопки можуть використовувати той самий об’єкт цілі, тому обидва запускають той самий код. HTTP цілі використовують одні й ті ж поля запиту:
Немає неявних стандартних значень запиту. Якщо ваш обробник повинен отримати сирові вхідні дані інструменту як JSON, напишіть 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'), замість цього повертайте звичайну помилку домену.
Kazzle зберігає карточку на виклику інструменту та відновлює через /chat/resume після натискання кнопки. Відповідні клієнти бачать кнопки автора; невідповідні клієнти все ще бачать Пропустити/Скасувати плюс «Продовжити на ». Кнопка без target подає свої input як результат інструменту. Кнопка з цільовою адресою спочатку запускає цю ціль, потім використовує результат цілі як результат інструменту.

Багатий інтерфейс — вбудуйте сторінку, розміщену додатком

Коли результат інструменту є візуальним або інтерактивним (екран підключення, діаграма, панель керування резюме), служіть сторінку з одного з ваших компонентів та повертайте її абсолютну URL як embedUrl. Побудуйте URL з введеної URL компонента — ніколи не відносний шлях.
Сторінка запускається в кросс-походженні iframe (її власне походження, файли cookie та скрипти). Щоб змінити розмір карточки, опублікуйте її висоту батьківському — карточка слухає це та змінює розмір (обмежено 70% вікна перегляду):
Віддавайте перевагу embedUrl над випусканням рядків HTML: ваш додаток уже служить сторінкам, інтерфейс залишається інтерактивним та версіонованим з вашим кодом, і жодні артефакти за виклик не записуються ніде.