エージェント駆動ワークフロー

ドメイン 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 を使うと、ドメイン API にまだ公開されていないものを含め、すべての MCP ツールに生の形でアクセスできます：

// 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 を呼び出すエージェントは、2 つのことを知っている必要があります。ツールがどんなパラメータを期待するか、そしてレスポンスがどんな形かです。SDK はこの情報を取得する 2 つの方法を提供します。

`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() はこれを使って、実行時に listTools() を呼び出さずにツールを Vercel AI SDK に接続します：

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 またはリソース名から、API 呼び出しなしで 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、マルチテナント、デフォルト以外のサーバー環境