代理程式驅動的工作流程

領域 API（stitch.projects()、project.generate()）是人類撰寫指令碼時的首選介面。但如果你正在建構 AI 代理程式、自動化管線，或需要取用領域層尚未包裝的工具，請改用較低階的 callTool 與 listTools API。

列出可用工具

探索 Stitch MCP 伺服器能做什麼：

import { stitch } from "@google/stitch-sdk";

const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

以名稱呼叫任何工具

callTool 讓你能直接存取每一個 MCP 工具，包括領域 API 尚未呈現的工具：

// Create a project
const result = await stitch.callTool("create_project", { title: "Agent Project" });
console.log(result);

// Generate a screen
const screen = await stitch.callTool("generate_screen_from_text", {
  projectId: result.name.replace("projects/", ""),
  prompt: "A dashboard with charts and KPIs",
});
console.log(screen);

代理程式如何探索工具結構描述

呼叫 callTool 的代理程式必須知道兩件事：工具預期什麼參數，以及回應會是什麼樣子。SDK 提供兩種取得這些資訊的方式。

使用 listTools() 在執行階段探索

呼叫 listTools() 以取得完整的工具目錄與其 JSON Schema。代理程式會讀取這些結構描述，了解該建構哪些引數：

const { tools } = await stitch.listTools();
const createTool = tools.find(t => t.name === "create_project");
console.log(JSON.stringify(createTool.inputSchema, null, 2));
// → { type: "object", properties: { title: { type: "string", ... } } }

接著代理程式就能依結構描述建構合法的 callTool 呼叫——無須事先硬編碼任何參數名稱。

使用 toolDefinitions 的靜態結構描述

SDK 也隨附一個在建置階段產生的 toolDefinitions 陣列（來自 tools-manifest.json），其中內嵌了相同的結構描述。stitchTools() 就是用它把工具接進 Vercel AI SDK，而不需要在執行階段呼叫 listTools()：

import { toolDefinitions } from "@google/stitch-sdk/tool-definitions"; // internal

for (const tool of toolDefinitions) {
  console.log(tool.name, Object.keys(tool.inputSchema.properties));
}

回應不具固定結構

callTool 會傳回 MCP 伺服器的原始 JSON——實際形狀取決於工具。代理程式應動態檢查回應，而不是假設固定結構。領域 API（project.generate()、screen.edit()）會將這些回應解析為具型別的物件，但在 callTool 層級，解讀結果是代理程式自己的責任。

混合使用領域 API 與工具 API

stitch 單例透過同一個物件同時提供這兩層。你可以用 callTool 建立資源，其餘的一切再改用領域 API：

// Create via callTool (agent-style)
const raw = await stitch.callTool("create_project", { title: "Hybrid Flow" });

// Switch to domain API (human-style)
const project = stitch.project(raw.name);
const screen = await project.generate("A settings page");
const html = await screen.getHtml();

這就是身分對應模式（identity map pattern）——stitch.project(id) 不會發出 API 呼叫，就能從任何專案 ID 或資源名稱建立 Project 控制代碼。用它就能在原始工具結果與流暢的領域 API 之間搭起橋樑。

建構自訂用戶端

如果你需要 OAuth 認證，或想連線到不同的 Stitch 環境，可以直接具現化 StitchToolClient：

import { StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({
  accessToken: process.env.STITCH_ACCESS_TOKEN,
  projectId: process.env.GOOGLE_CLOUD_PROJECT,
});

await client.connect();
const tools = await client.listTools();
console.log(`${tools.tools.length} tools available`);

await client.close();

何時該用哪一種

模式	最適合
領域 API（stitch.projects() → project.generate() → screen.getHtml()）	人工撰寫的指令碼、教學、單純直接的工作流程
callTool	AI 代理程式、自動化、不在領域層中的工具、動態工具選擇
stitchTools()	Vercel AI SDK 整合——請參閱搭配 AI SDK 使用
自訂 StitchToolClient	OAuth、多租戶，或非預設的伺服器環境