diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 06bc3b3..47cf7a9 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -30,6 +30,8 @@ To use `stitchTools()` with the [Vercel AI SDK](https://sdk.vercel.ai/), install npm install @google/stitch-sdk ai ``` +See [examples/tool-filtering](./examples/tool-filtering) for an example of filtering available tools with the `include` parameter. + ## Working with Projects and Screens ### List existing projects diff --git a/packages/sdk/examples/tool-filtering/README.md b/packages/sdk/examples/tool-filtering/README.md new file mode 100644 index 0000000..fd94b91 --- /dev/null +++ b/packages/sdk/examples/tool-filtering/README.md @@ -0,0 +1,20 @@ +# Tool Filtering Example + +This example demonstrates how to use `stitchTools({ include: [...] })` to restrict which tools an LLM can call when using the Vercel AI SDK adapter. + +## Why Filter Tools? + +By default, `stitchTools()` provides all available Stitch MCP tools to the LLM. In many workflows, you want to restrict the LLM's capabilities to prevent unintended actions. For example: +- **Read-only Agent**: Only provide `list_projects`, `list_screens`, and `get_screen` to prevent the agent from creating or editing designs. +- **Iteration Agent**: Only provide `edit_screen` and `generate_screen_variants` if the agent's only job is to refine an existing design. + +## Usage + +Run the example script: + +```bash +cd packages/sdk +STITCH_API_KEY=your-api-key bun examples/tool-filtering/index.ts +``` + +The script will output the filtered list of tools to demonstrate that the output is successfully constrained. diff --git a/packages/sdk/examples/tool-filtering/index.ts b/packages/sdk/examples/tool-filtering/index.ts new file mode 100644 index 0000000..93b30fc --- /dev/null +++ b/packages/sdk/examples/tool-filtering/index.ts @@ -0,0 +1,47 @@ +/** + * Demonstrates how to use Vercel AI SDK with a filtered list of Stitch tools. + * + * In a real scenario, you would pass `tools` to `generateText()` along with a + * Vercel AI SDK language model. This example logs the filtered tool configuration. + * + * Usage: + * STITCH_API_KEY=your-key bun packages/sdk/examples/tool-filtering/index.ts + */ +import { stitchTools } from "@google/stitch-sdk/ai"; + +import "../_require-key.js"; + +console.log("šŸ” Demonstrating Vercel AI SDK tool filtering..."); + +// Generate tools but ONLY provide the tools that allow reading projects/screens. +// This prevents the LLM from creating or modifying data. +const readOnlyTools = stitchTools({ + include: ["list_projects", "list_screens", "get_screen"], +}); + +console.log(`\nāœ… Generated ${Object.keys(readOnlyTools).length} read-only tools:`); +for (const [name, tool] of Object.entries(readOnlyTools)) { + console.log(` - ${name}: ${tool.description?.slice(0, 80)}...`); +} + +// Generate tools but ONLY provide tools related to design iteration. +const iterationTools = stitchTools({ + include: ["edit_screen", "generate_screen_variants_from_text"], +}); + +console.log(`\nāœ… Generated ${Object.keys(iterationTools).length} iteration tools:`); +for (const [name, tool] of Object.entries(iterationTools)) { + console.log(` - ${name}: ${tool.description?.slice(0, 80)}...`); +} + +console.log("\nšŸ’” Usage with Vercel AI SDK:"); +console.log(` +import { generateText } from "ai"; + +const { text } = await generateText({ + model: yourModel, + tools: readOnlyTools, // LLM can only read, not write! + prompt: "What projects do I have?", + maxSteps: 5, +}); +`);