ツール

ツールは、AI が呼び出せる名前付きアクション（型付き入力付き）です。例えば send_email(to, subject, body) のようなものです。ツールはスキルの tools.ts で宣言され、アプリが提供するツールの場合、コンポーネントの HTTP ルートでサポートされます。このページはツール契約の信頼できる情報源です。tools.ts がどこにあるかについては、スキルを参照してください。

ツールの宣言

tools.ts の各エントリには、プロバイダー安全な name、フレンドリーな displayName、description、Zod の input スキーマ、および Kazzle が呼び出すものを指定する target があります。

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 はツールまたは必須アクションボタンの再利用可能なアドレスです。直接的な AI ツール呼び出しとボタンクリックは同じターゲットオブジェクトを使用できるため、両方とも同じコードを実行します。

ターゲット	フィールド	実行場所
`app`	`component`、`path`、`method`、オプション `query`、`headers`、`body`	自分のコンポーネントの 1 つ。Kazzle はコンポーネント URL を解決し、署名されたアプリ ID トークンを追加します。
`url`	`url`、`method`、オプション `query`、`headers`、`body`	外部エンドポイント。URL オリジンとメソッドはリテラル作成者値です。
`kazzle`	`name`	組み込みクライアント側 Kazzle ハンドラー。

HTTP ターゲットは同じリクエストフィールドを使用します：

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

暗黙的なリクエストデフォルトはありません。ハンドラーが生のツール入力を 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 ボディとして送信します：

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

app ターゲットは以下も受け取ります：

ヘッダー	値
`Authorization`	`Bearer <identity token>` ユーザー + インストールを識別します
`Kazzle-Tool-Context`	`{"source":"thread","threadId":"..."}` または `{"source":"api"}`

アプリターゲットは headers を通じて Authorization を設定できません。Kazzle がそのヘッダーを所有しています。ハンドラーがスレッド対ツール API を分岐する必要がある場合は、@kazzle/app/tools から toolContext(req) でコンテキストを読み取ります。一致するルートなしで宣言されたツールは役に立ちません。両方を一緒に追加します。tools.json はサポートされていません。アプリコンパイラーが見つけた場合は失敗します。

ハンドラーレスポンス

プレーンテキスト、または最大 3 つのチャネルを持つ JSON を返します：

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

content — AI が読むプレーン結果（モデルに供給されます）。必須。
markdown — オプション。ツールカードにレンダリングされる短いリッチテキスト概要（react-markdown；生の HTML はエスケープされます）。文、小さなリスト、インラインリンクに適しています。ベアの相対パスはデッドプリフォーマットテキストとしてレンダリングされます。リンクは絶対である必要があります。
embedUrl — オプション。アプリが提供する絶対 URL。カードはそれをサンドボックス化された iframe でレンダリングします。これは実際のフルウィッドス UI（接続画面、ダッシュボード、チャート）を表示する方法です。アプリはページをホストして所有するため、独自のバックエンド、クッキー、OAuth に対して完全にインタラクティブにできます。ドライブには何も書き込まれません。

両方が設定されている場合、embedUrl は markdown に優先します。常に意味のある content を保持してください。それが AI が読むものです。

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

必須アクション

アプリツールはユーザー（またはデバイス）アクションが必要な場合、スレッドを一時停止できます。カードタイトルとボタンを含む type: 'action_required' を返します。toolContext(req).source === 'thread' の場合のみ有効です。ツール API（source: 'api'）では、代わりに通常のドメインエラーを返します。

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 はツール呼び出しのカードを保存し、ボタンが押された後 /chat/resume を通じて再開します。一致するクライアントは作成者ボタンを表示します。一致しないクライアントは、スキップ/キャンセルと「で続行」を表示します。target のないボタンはその input をツール結果として送信します。ターゲット付きボタンはそのターゲットを最初に実行し、ターゲット結果をツール結果として使用します。

リッチ UI — アプリホストページを埋め込む

ツールの結果がビジュアルまたはインタラクティブ（接続画面、チャート、概要ダッシュボード）の場合、コンポーネントの 1 つからページを提供し、その絶対 URL を embedUrl として返します。注入されたコンポーネント URL から URL を構築します。相対パスは使用しないでください。

// ユーザーがアカウントを接続する必要があるツール：
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}`,
});

ページはクロスオリジン iframe（独自のオリジン、クッキー、スクリプト）で実行されます。カードのサイズを変更するには、その高さを親に投稿します。カードはこれをリッスンしてサイズを変更します（ビューポートの 70% でキャップされます）：

// 埋め込まれたページ内
parent.postMessage({ __kazzle_height: document.body.scrollHeight }, '*');

HTML 文字列を出力する代わりに embedUrl を優先します。アプリは既にページを提供しており、UI はインタラクティブでコードとバージョン管理されたままであり、呼び出しごとのアーティファクトはどこにも書き込まれません。

はじめに

作成

ユーザーとデータ

公開

Kazzle の使い方

セキュリティ

リファレンス

ツール

ツール

ツールの宣言

ターゲット

リファレンス

ハンドラーリクエスト

ハンドラーレスポンス

必須アクション

リッチ UI — アプリホストページを埋め込む

​ツール

​ツールの宣言

​ターゲット

​リファレンス

​ハンドラーリクエスト

​ハンドラーレスポンス

​必須アクション

​リッチ UI — アプリホストページを埋め込む

ツール

ツールの宣言

ターゲット

リファレンス

ハンドラーリクエスト

ハンドラーレスポンス

必須アクション

リッチ UI — アプリホストページを埋め込む