Strumenti

Uno strumento è un’azione denominata che l’AI può invocare, con input tipizzati — ad es. send_email(to, subject, body). Gli strumenti sono dichiarati nel file tools.ts di una skill e, per gli strumenti che la tua app fornisce, supportati da una rotta HTTP in uno dei tuoi componenti. Questa pagina è la fonte di verità per il contratto dello strumento; Skills spiega dove si trova tools.ts.

Dichiarare uno strumento

Ogni voce in tools.ts ha un name sicuro per il provider, un displayName descrittivo, una description, uno schema Zod input e un target che specifica cosa Kazzle invoca.

import { z } from 'zod';
import type { KazzleTool } from '@kazzle/app/tools';

export const SaveBookmarkInput = z.object({
  url: z.string().url().describe('URL to save.'),
  title: z.string().optional().describe('Optional human-readable title.'),
}).strict();

const saveBookmarkTarget = {
  type: 'app',
  component: 'api',
  path: '/tools/save-bookmark',
  method: 'POST',
  body: '${input}',
} as const;

export const tools = [
  {
    name: 'save_bookmark',
    displayName: 'Save bookmark',
    description: 'Save a bookmark URL and return a confirmation.',
    input: SaveBookmarkInput,
    target: saveBookmarkTarget,
  },
] as const satisfies readonly KazzleTool[];

Target

target è l’indirizzo riutilizzabile per uno strumento o un pulsante di azione richiesta. Una chiamata diretta dello strumento AI e un clic del pulsante possono usare lo stesso oggetto target, quindi entrambi eseguono lo stesso codice.

Target	Campi	Eseguito dove
`app`	`component`, `path`, `method`, `query` opzionale, `headers`, `body`	In uno dei tuoi componenti. Kazzle risolve l’URL del componente e aggiunge un token di identità dell’app firmato.
`url`	`url`, `method`, `query` opzionale, `headers`, `body`	Un endpoint esterno. L’origine dell’URL e il metodo sono valori letterali dell’autore.
`kazzle`	`name`	Un handler Kazzle integrato lato client.

I target HTTP usano gli stessi campi di richiesta:

type RequestSpec = {
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  query?: Record<string, string>;
  headers?: Record<string, string>;
  body?: unknown;
};

Non ci sono impostazioni predefinite implicite per la richiesta. Se il tuo handler deve ricevere l’input dello strumento grezzo come JSON, scrivi body: '${input}'.

Riferimenti

Kazzle risolve i riferimenti nei campi query, headers, body e url del target HTTP prima dell’invio:

${input} — l’intero input dello strumento, o l’intero input del pulsante.
${input.path} — un valore annidato dall’input.
${env.NAME} — una variabile d’ambiente denominata dalla env.collection dichiarata del componente app proprietario + env.environment.

La risoluzione è a passaggio singolo. Se un riferimento è mancante o sconosciuto, lo strumento fallisce invece di sostituire un valore vuoto. Usa $${input.name} quando hai bisogno del testo letterale ${input.name}.

Richiesta del handler

Per un target app, aggiungi la rotta corrispondente nel componente target. Con body: '${input}', Kazzle invia l’input tipizzato come corpo JSON:

{ "...": "the typed input" }

I target app ricevono anche:

Header	Valore
`Authorization`	`Bearer <identity token>` che identifica l’utente + installazione
`Kazzle-Tool-Context`	`{"source":"thread","threadId":"..."}` o `{"source":"api"}`

I target app non possono impostare Authorization tramite headers; Kazzle possiede quell’header. Leggi il contesto con toolContext(req) da @kazzle/app/tools quando l’handler deve distinguere tra thread e Tools API. Uno strumento dichiarato senza una rotta corrispondente non è utile — aggiungili entrambi. tools.json non è supportato; il compilatore dell’app fallisce se ne trova uno.

Risposta del handler

Restituisci testo semplice, o JSON con fino a tre canali:

{ "content": "...", "markdown": "...", "embedUrl": "https://..." }

content — il risultato semplice che l’AI legge (fornito al modello). Obbligatorio.
markdown — opzionale. Un breve riepilogo in testo ricco renderizzato nella scheda dello strumento (react-markdown; l’HTML grezzo è sfuggito). Adatto per una frase, un piccolo elenco, un link inline. Un percorso relativo nudo viene renderizzato come testo preformattato morto — i link devono essere assoluti.
embedUrl — opzionale. Un URL assoluto che la tua app fornisce; la scheda lo renderizza in un iframe sandbox. Questo è il modo per mostrare un’interfaccia utente reale e a larghezza intera — una schermata di connessione, una dashboard, un grafico. La tua app ospita e possiede la pagina, quindi può essere completamente interattiva con il tuo backend, i cookie e OAuth. Nulla viene scritto nel drive.

embedUrl ha la precedenza su markdown quando entrambi sono impostati. Mantieni sempre un content significativo — è quello che l’AI legge.

if (req.method === 'POST' && new URL(req.url).pathname === '/tools/save-bookmark') {
  const input = await req.json();
  // ...do the work...
  return Response.json({ content: `Saved ${input.title}` });
}

Azione richiesta

Uno strumento app può mettere in pausa il thread quando ha bisogno di un’azione dell’utente (o del dispositivo). Restituisci type: 'action_required' con un titolo della scheda e pulsanti. Valido solo quando toolContext(req).source === 'thread' — tramite Tools API (source: 'api'), restituisci invece un errore di dominio normale.

import { toolContext, isThreadToolInvocation } from '@kazzle/app/tools';

const context = toolContext(req);
if (!isThreadToolInvocation(context)) {
  return Response.json(
    { code: 'connect_required', error: 'Gmail must be connected before this tool can run.' },
    { status: 409 },
  );
}

return Response.json({
  type: 'action_required',
  title: 'Connect Gmail',
  description: 'Connect Gmail before Kazzle can search messages.',
  // Optional: only this device may run the gated buttons
  // assignee: { computerId: '<from computer { list: {} }>' },
  elements: [
    {
      type: 'button',
      id: 'connect',
      label: 'Connect Gmail',
      variant: 'primary',
      input: { scope: 'gmail.readonly' },
      target: {
        type: 'app',
        component: 'api',
        path: '/oauth/start',
        method: 'POST',
        body: '${input}',
      },
    },
  ],
});

Kazzle salva la scheda sulla chiamata dello strumento e riprende tramite /chat/resume dopo che un pulsante è stato premuto. I client corrispondenti vedono i pulsanti dell’autore; i client non corrispondenti vedono ancora Skip/Cancel più “Continue on ”. Un pulsante senza target invia il suo input come risultato dello strumento. Un pulsante con un target esegue prima quel target, quindi usa il risultato del target come risultato dello strumento.

Interfaccia utente ricca — incorpora una pagina ospitata dall’app

Quando il risultato di uno strumento è visivo o interattivo (una schermata di connessione, un grafico, una dashboard di riepilogo), fornisci la pagina da uno dei tuoi componenti e restituisci il suo URL assoluto come embedUrl. Costruisci l’URL dall’URL del componente iniettato — mai un percorso relativo.

// A tool that needs the user to connect their account:
return Response.json({
  content: "Gmail isn't connected yet — the user needs to connect it.",
  embedUrl: `${process.env.KAZZLE_APP_COMPONENT_URL}/connect?token=${identity}`,
});

La pagina viene eseguita in un iframe cross-origin (la sua origine, i cookie e gli script). Per dimensionare la scheda, invia la sua altezza al genitore — la scheda ascolta questo e si ridimensiona (limitato al 70% del viewport):

// inside the embedded page
parent.postMessage({ __kazzle_height: document.body.scrollHeight }, '*');

Preferisci embedUrl rispetto all’emissione di stringhe HTML: la tua app fornisce già pagine, l’interfaccia utente rimane interattiva e versionata con il tuo codice, e nessun artefatto per chiamata viene scritto da nessuna parte.

Per iniziare

Costruire

Utenti e dati

Pubblicare

Usare Kazzle

Sicurezza

Riferimento

Strumenti

Strumenti

Dichiarare uno strumento

Target

Riferimenti

Richiesta del handler

Risposta del handler

Azione richiesta

Interfaccia utente ricca — incorpora una pagina ospitata dall’app

​Strumenti

​Dichiarare uno strumento

​Target

​Riferimenti

​Richiesta del handler

​Risposta del handler

​Azione richiesta

​Interfaccia utente ricca — incorpora una pagina ospitata dall’app

Strumenti

Dichiarare uno strumento

Target

Riferimenti

Richiesta del handler

Risposta del handler

Azione richiesta

Interfaccia utente ricca — incorpora una pagina ospitata dall’app