工具

工具是 AI 可以呼叫的具名動作，具有型別化輸入 — 例如 send_email(to, subject, body)。工具在技能的 tools.ts 中聲明，對於應用程式提供的工具，由其中一個元件中的 HTTP 路由支援。本頁面是工具合約的真實來源；技能涵蓋 tools.ts 的位置。

聲明工具

tools.ts 中的每個項目都有一個提供者安全的 name、一個友善的 displayName、一個 description、一個 Zod input 結構描述，以及一個 target 來指定 Kazzle 呼叫的內容。

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`	您自己的其中一個元件。Kazzle 解析元件 URL 並新增已簽署的應用程式身分識別權杖。
`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；如果應用程式編譯器找到一個，它會失敗。

處理程式回應

返回純文字或 JSON，最多三個通道：

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

content — AI 讀取的純文字結果（提供給模型）。必要。
markdown — 選用。在工具卡中呈現的簡短富文字摘要（react-markdown；原始 HTML 會被逸出）。適合一個句子、一個小清單、一個內嵌連結。裸露相對路徑呈現為無效預先格式化文字 — 連結必須是絕對。
embedUrl — 選用。您的應用程式提供的絕對 URL；卡片在沙箱 iframe 中呈現它。這是您顯示真實、全寬 UI 的方式 — 連線畫面、儀表板、圖表。您的應用程式裝載並擁有該頁面，因此它可以針對您自己的後端、Cookie 和 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 — 嵌入應用程式裝載的頁面

當工具的結果是視覺或互動式的（連線畫面、圖表、摘要儀表板）時，從您的其中一個元件提供頁面，並將其絕對 URL 返回為 embedUrl。從注入的元件 URL 建立 URL — 絕不是相對路徑。

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

該頁面在跨來源 iframe（其自己的來源、Cookie 和指令碼）中執行。若要調整卡片大小，請將其高度發佈到父項 — 卡片會監聽此項並調整大小（上限為檢視區 70%）：

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

優先使用 embedUrl 而不是發出 HTML 字串：您的應用程式已經提供頁面、UI 保持互動式並與您的程式碼版本化，並且沒有每次呼叫的成品寫入任何地方。

開始使用

建構

使用者與資料

發佈

使用 Kazzle

安全性

參考

工具

工具

聲明工具

目標

參考資料

處理程式請求

處理程式回應

必要動作

豐富 UI — 嵌入應用程式裝載的頁面

​工具

​聲明工具

​目標

​參考資料

​處理程式請求

​處理程式回應

​必要動作

​豐富 UI — 嵌入應用程式裝載的頁面

工具

聲明工具

目標

參考資料

處理程式請求

處理程式回應

必要動作

豐富 UI — 嵌入應用程式裝載的頁面