Skip to main content
Integrate Moss semantic search into Vercel AI SDK agents using the @moss-tools/vercel-sdk package. This setup exposes Moss operations as AI SDK tools, so language models can search, create indexes, and manage documents as part of agentic workflows.
Note: For the full package source and tests, see the vercel-sdk package.

​
Why use Moss with the Vercel AI SDK?

The Vercel AI SDK’s tool system lets language models call external functions during generation. Moss tools give your agents direct access to a semantic knowledge base with sub-10ms retrieval, enabling RAG workflows and knowledge base operations within a single generateText or streamText call.

​
Required tools

​
Integration guide

1

Installation

npm install @moss-tools/vercel-sdk @inferedge/moss ai zod
2

Environment setup

.env.local
MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_project_key
OPENAI_API_KEY=sk-...
3

Create tools and use with an agent

Import the tool factories and initialize them with a Moss client. Each factory returns a standard AI SDK tool with typed input/output schemas.
import { MossClient } from "@inferedge/moss";
import {
  mossSearchTool,
  mossAddDocsTool,
  mossDeleteDocsTool,
  mossCreateIndexTool,
  mossListIndexesTool,
} from "@moss-tools/vercel-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const client = new MossClient(
  process.env.MOSS_PROJECT_ID!,
  process.env.MOSS_PROJECT_KEY!,
);

// Prebind tools to a specific index for simpler schemas
const tools = {
  search: mossSearchTool({ client, indexName: "docs" }),
  addDocs: mossAddDocsTool({ client, indexName: "docs" }),
  deleteDocs: mossDeleteDocsTool({ client, indexName: "docs" }),
  createIndex: mossCreateIndexTool({ client }),
  listIndexes: mossListIndexesTool({ client }),
};

const result = await generateText({
  model: openai("gpt-4o"),
  tools,
  stopWhen: stepCountIs(5),
  prompt: "Search the docs index for return policy info and summarize it.",
});

​
Available tools

​
Read-only

ToolDescription
mossSearchToolSemantic search over an index. Returns matching documents ranked by similarity.
mossListIndexesToolList all available indexes in the Moss project.

​
Mutating (requires approval)

Mutating tools have needsApproval: true, so the AI SDK prompts for user confirmation before execution.
ToolDescription
mossAddDocsToolAdd documents to an existing index. Supports upsert by document ID.
mossDeleteDocsToolDelete documents from an index by their IDs.
mossCreateIndexToolCreate a new index with initial documents.

​
Configuration

​
Index binding

Tools accept an optional indexName parameter. When provided, the tool is prebound to that index and the LLM only needs to provide the query or document data. When omitted, the LLM chooses the index name dynamically. 
// Prebound: simpler schema, LLM only provides query
const search = mossSearchTool({ client, indexName: "docs" });

// Dynamic: LLM chooses the index
const search = mossSearchTool({ client });

​
mossSearchTool options

ParameterTypeDefaultDescription
clientMossClientRequiredAn initialized Moss client instance.
indexNamestringundefinedPrebind to a specific index.
descriptionstringAuto-generatedCustom tool description for the LLM.