Tools

Ein Tool ist eine benannte Aktion, die die KI aufrufen kann, mit typisierten Eingaben — z. B. send_email(to, subject, body). Tools werden in der tools.ts einer Skill deklariert und, für Tools, die deine App bereitstellt, durch eine HTTP-Route in einer deiner Komponenten unterstützt. Diese Seite ist die Quelle der Wahrheit für den Tool-Vertrag; Skills behandelt, wo tools.ts lebt.

Ein Tool deklarieren

Jeder Eintrag in tools.ts hat einen Provider-sicheren name, einen benutzerfreundlichen displayName, eine description, ein Zod-input-Schema und ein target, das angibt, was Kazzle aufruft.

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 ist die wiederverwendbare Adresse für ein Tool oder eine erforderliche Aktionsschaltfläche. Ein direkter KI-Tool-Aufruf und ein Schaltflächenklick können dasselbe Target-Objekt verwenden, sodass beide denselben Code ausführen.

Target	Felder	Läuft wo
`app`	`component`, `path`, `method`, optional `query`, `headers`, `body`	In einer deiner eigenen Komponenten. Kazzle löst die Komponenten-URL auf und fügt ein signiertes App-Identity-Token hinzu.
`url`	`url`, `method`, optional `query`, `headers`, `body`	Ein externer Endpunkt. Die URL-Origin und Methode sind Literalwerte des Autors.
`kazzle`	`name`	Ein integrierter clientseitiger Kazzle-Handler.

HTTP-Targets verwenden dieselben Request-Felder:

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

Es gibt keine impliziten Request-Standardwerte. Wenn dein Handler die rohe Tool-Eingabe als JSON erhalten soll, schreibe body: '${input}'.

Referenzen

Kazzle löst Referenzen in HTTP-Target-Feldern query, headers, body und url vor dem Versand auf:

${input} — die gesamte Tool-Eingabe oder die gesamte Button-Eingabe.
${input.path} — ein verschachtelter Wert aus der Eingabe.
${env.NAME} — eine benannte Umgebungsvariable aus der deklarierten env.collection + env.environment der besitzenden App-Komponente.

Die Auflösung erfolgt in einem Durchgang. Wenn eine Referenz fehlt oder unbekannt ist, schlägt das Tool fehl, anstatt einen leeren Wert zu ersetzen. Verwende $${input.name}, wenn du literalen ${input.name}-Text benötigst.

Handler-Request

Für ein app-Target füge die entsprechende Route in der Target-Komponente hinzu. Mit body: '${input}' sendet Kazzle die typisierte Eingabe als JSON-Body:

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

app-Targets erhalten auch:

Header	Wert
`Authorization`	`Bearer <identity token>` identifiziert den Benutzer + Installation
`Kazzle-Tool-Context`	`{"source":"thread","threadId":"..."}` oder `{"source":"api"}`

App-Targets können Authorization nicht über headers setzen; Kazzle besitzt diesen Header. Lese den Kontext mit toolContext(req) aus @kazzle/app/tools, wenn der Handler zwischen Thread und Tools API unterscheiden muss. Ein Tool, das ohne entsprechende Route deklariert wird, ist nicht sonderlich nützlich — füge beide zusammen hinzu. tools.json wird nicht unterstützt; der App-Compiler schlägt fehl, wenn er eine findet.

Handler-Response

Gib Klartext oder JSON mit bis zu drei Kanälen zurück:

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

content — das einfache Ergebnis, das die KI liest (an das Modell weitergeleitet). Erforderlich.
markdown — optional. Eine kurze Rich-Text-Zusammenfassung, die in der Tool-Karte gerendert wird (react-markdown; rohes HTML wird escaped). Gut für einen Satz, eine kleine Liste, einen Inline-Link. Ein bloßer relativer Pfad wird als totes vorformatiertes Text gerendert — Links müssen absolut sein.
embedUrl — optional. Eine absolute URL, die deine App bereitstellt; die Karte rendert sie in einem Sandbox-iframe. So zeigst du eine echte, vollständige UI — einen Connect-Bildschirm, ein Dashboard, ein Diagramm. Deine App hostet und besitzt die Seite, sodass sie vollständig interaktiv gegen dein eigenes Backend, Cookies und OAuth sein kann. Nichts wird auf das Drive geschrieben.

embedUrl gewinnt über markdown, wenn beide gesetzt sind. Behalte immer einen aussagekräftigen content — das ist das, was die KI liest.

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

Erforderliche Aktion

Ein App-Tool kann den Thread pausieren, wenn es eine Benutzer- (oder Geräte-)Aktion benötigt. Gib type: 'action_required' mit einem Kartentitel und Schaltflächen zurück. Nur gültig, wenn toolContext(req).source === 'thread' — über die Tools API (source: 'api'), gib stattdessen einen normalen Domain-Fehler zurück.

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 speichert die Karte beim Tool-Aufruf und setzt fort über /chat/resume, nachdem eine Schaltfläche gedrückt wurde. Übereinstimmende Clients sehen die Autor-Schaltflächen; nicht übereinstimmende Clients sehen immer noch Skip/Cancel plus „Auf fortsetzen”. Eine Schaltfläche ohne target sendet ihre input als Tool-Ergebnis. Eine Schaltfläche mit einem Target führt dieses Target zuerst aus, dann verwendet das Target-Ergebnis als Tool-Ergebnis.

Rich UI — eine App-gehostete Seite einbetten

Wenn das Ergebnis eines Tools visuell oder interaktiv ist (ein Connect-Bildschirm, ein Diagramm, ein Zusammenfassungs-Dashboard), stelle die Seite von einer deiner Komponenten bereit und gib ihre absolute URL als embedUrl zurück. Erstelle die URL aus der eingespritzt Komponenten-URL — niemals ein relativer Pfad.

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

Die Seite läuft in einem Cross-Origin-iframe (ihre eigene Origin, Cookies und Scripts). Um die Karte zu dimensionieren, poste ihre Höhe zum Parent — die Karte hört darauf und ändert die Größe (begrenzt auf 70% des Viewports):

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

Bevorzuge embedUrl gegenüber der Ausgabe von HTML-Strings: Deine App stellt bereits Seiten bereit, die UI bleibt interaktiv und versioniert mit deinem Code, und keine Pro-Aufruf-Artefakte werden irgendwo geschrieben.

Erste Schritte

Erstellen

Nutzer und Daten

Veröffentlichen

Kazzle verwenden

Sicherheit

Referenz

Tools

Tools

Ein Tool deklarieren

Targets

Referenzen

Handler-Request

Handler-Response

Erforderliche Aktion

Rich UI — eine App-gehostete Seite einbetten

​Tools

​Ein Tool deklarieren

​Targets

​Referenzen

​Handler-Request

​Handler-Response

​Erforderliche Aktion

​Rich UI — eine App-gehostete Seite einbetten

Tools

Ein Tool deklarieren

Targets

Referenzen

Handler-Request

Handler-Response

Erforderliche Aktion

Rich UI — eine App-gehostete Seite einbetten