智能体驱动的工作流

领域 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);

智能体如何发现工具 schema

调用 callTool 的智能体需要知道两件事：工具期望什么参数，以及响应长什么样。SDK 提供两种获取这些信息的方式。

使用 listTools() 进行运行时发现

调用 listTools() 可以拿到包含 JSON Schema 的完整工具目录。智能体通过阅读这些 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", ... } } }

之后智能体就能根据 schema 构造出有效的 callTool 调用——无需硬编码参数名的知识。

使用 toolDefinitions 的静态 schema

SDK 还内置了一个生成的 toolDefinitions 数组（来自 tools-manifest.json），在构建时就写入了相同的 schema。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();

这就是标识映射模式——stitch.project(id) 可以从任意项目 ID 或资源名称创建一个 Project 句柄，且不会发起 API 调用。用它来衔接原始工具结果和流畅的领域 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、多租户或非默认服务器环境