Tools

Een tool is een benoemde actie die de AI kan aanroepen, met getypeerde invoer — bijv. send_email(to, subject, body). Tools worden gedeclareerd in de tools.ts van een skill en, voor tools die je app aanbiedt, ondersteund door een HTTP-route in een van je componenten. Deze pagina is de bron van waarheid voor het tool-contract; Skills behandelt waar tools.ts zich bevindt.

Een tool declareren

Elk item in tools.ts heeft een provider-veilige name, een vriendelijke displayName, een description, een Zod input-schema, en een target die aangeeft wat Kazzle aanroept.

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[];

Targets

target is het herbruikbare adres voor een tool of vereiste-actie-knop. Een directe AI-tool-aanroep en een knopklik kunnen hetzelfde target-object gebruiken, dus beide voeren dezelfde code uit.

Target	Velden	Wordt uitgevoerd waar
`app`	`component`, `path`, `method`, optioneel `query`, `headers`, `body`	In een van je eigen componenten. Kazzle lost de component-URL op en voegt een ondertekend app-identiteitstoken toe.
`url`	`url`, `method`, optioneel `query`, `headers`, `body`	Een extern eindpunt. De URL-oorsprong en methode zijn letterlijke auteurwaarden.
`kazzle`	`name`	Een ingebouwde client-side Kazzle-handler.

HTTP-targets gebruiken dezelfde aanvraagvelden:

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

Er zijn geen impliciete aanvraagstandaards. Als je handler de onbewerkte tool-invoer als JSON moet ontvangen, schrijf je body: '${input}'.

Referenties

Kazzle lost referenties op in HTTP-target query-, headers-, body- en url-velden vóór verzending:

${input} — de hele tool-invoer, of de hele knop-invoer.
${input.path} — een geneste waarde uit de invoer.
${env.NAME} — een benoemde omgevingsvariabele uit de gedeclareerde env.collection + env.environment van de eigenaar-app-component.

Resolutie is eenmalig. Als een referentie ontbreekt of onbekend is, mislukt de tool in plaats van een lege waarde in te vullen. Gebruik $${input.name} wanneer je letterlijke ${input.name}-tekst nodig hebt.

Handler-aanvraag

Voor een app-target voeg je de overeenkomende route toe in de target-component. Met body: '${input}' stuurt Kazzle de getypeerde invoer als JSON-body:

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

app-targets ontvangen ook:

Header	Waarde
`Authorization`	`Bearer <identity token>` die de gebruiker + installatie identificeert
`Kazzle-Tool-Context`	`{"source":"thread","threadId":"..."}` of `{"source":"api"}`

App-targets kunnen Authorization niet instellen via headers; Kazzle bezit die header. Lees de context met toolContext(req) uit @kazzle/app/tools wanneer de handler thread vs Tools API moet onderscheiden. Een tool gedeclareerd zonder overeenkomende route doet niets nuttigs — voeg beide samen toe. tools.json wordt niet ondersteund; de app-compiler mislukt als deze er een vindt.

Handler-respons

Retourneer platte tekst, of JSON met maximaal drie kanalen:

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

content — het platte resultaat dat de AI leest (gevoerd naar het model). Vereist.
markdown — optioneel. Een korte rich-text-samenvatting weergegeven in de tool-kaart (react-markdown; onbewerkte HTML wordt ontsnapt). Goed voor een zin, een kleine lijst, een inline-link. Een bloot relatief pad wordt weergegeven als dode voorgeformateerde tekst — links moeten absoluut zijn.
embedUrl — optioneel. Een absolute URL die je app aanbiedt; de kaart geeft deze weer in een sandbox-iframe. Dit is hoe je een echte, volledige-breedte-UI toont — een verbindingsscherm, een dashboard, een grafiek. Je app host en bezit de pagina, dus deze kan volledig interactief zijn tegen je eigen backend, cookies en OAuth. Niets wordt naar de drive geschreven.

embedUrl wint van markdown wanneer beide zijn ingesteld. Behoud altijd een betekenisvolle content — dat is wat de AI leest.

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}` });
}

Vereiste actie

Een app-tool kan de thread pauzeren wanneer deze een gebruikers- (of apparaat-)actie nodig heeft. Retourneer type: 'action_required' met een kaarttitel en knoppen. Alleen geldig wanneer toolContext(req).source === 'thread' — over de Tools API (source: 'api'), retourneer in plaats daarvan een normale domeinenfout.

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 slaat de kaart op bij de tool-aanroep en hervat via /chat/resume nadat een knop is ingedrukt. Overeenkomende clients zien de auteurknoppen; niet-overeenkomende clients zien nog steeds Overslaan/Annuleren plus “Doorgaan op ”. Een knop zonder target dient zijn input in als het tool-resultaat. Een knop met een target voert eerst dat target uit, en gebruikt vervolgens het target-resultaat als het tool-resultaat.

Rich UI — een app-gehoste pagina insluiten

Wanneer het resultaat van een tool visueel of interactief is (een verbindingsscherm, een grafiek, een samenvattingsdashboard), dien je de pagina vanuit een van je componenten en retourneer je de absolute URL als embedUrl. Bouw de URL op uit de geïnjecteerde component-URL — nooit een relatief pad.

// 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}`,
});

De pagina wordt uitgevoerd in een cross-origin iframe (zijn eigen oorsprong, cookies en scripts). Om de kaart in grootte aan te passen, post je de hoogte naar de parent — de kaart luistert hiernaar en past de grootte aan (begrensd tot 70% van de viewport):

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

Geef de voorkeur aan embedUrl boven het uitzenden van HTML-strings: je app dient al pagina’s, de UI blijft interactief en versioned met je code, en er worden geen per-aanroep-artefacten ergens geschreven.

Aan de slag

Bouwen

Gebruikers en gegevens

Publiceren

Kazzle gebruiken

Beveiliging

Referentie

Tools

Tools

Een tool declareren

Targets

Referenties

Handler-aanvraag

Handler-respons

Vereiste actie

Rich UI — een app-gehoste pagina insluiten

​Tools

​Een tool declareren

​Targets

​Referenties

​Handler-aanvraag

​Handler-respons

​Vereiste actie

​Rich UI — een app-gehoste pagina insluiten

Tools

Een tool declareren

Targets

Referenties

Handler-aanvraag

Handler-respons

Vereiste actie

Rich UI — een app-gehoste pagina insluiten