Moss - Real-time Semantic Search for Conversational AI

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

Moss account with project credentials
Node.js 18+

Integration guide

Installation

npm install @moss-tools/vercel-sdk @moss-dev/moss ai zod

Environment setup

.env.local

MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_project_key
OPENAI_API_KEY=sk-...

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 "@moss-dev/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

Tool	Description
`mossSearchTool`	Semantic search over an index. Returns matching documents ranked by similarity.
`mossListIndexesTool`	List 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.

Tool	Description
`mossAddDocsTool`	Add documents to an existing index. Supports upsert by document ID.
`mossDeleteDocsTool`	Delete documents from an index by their IDs.
`mossCreateIndexTool`	Create 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

Parameter	Type	Default	Description
`client`	`MossClient`	Required	An initialized Moss client instance.
`indexName`	`string`	`undefined`	Prebind to a specific index.
`description`	`string`	Auto-generated	Custom tool description for the LLM.

Voice & Real-time

AI Frameworks

Developer Tools

Vercel AI SDK

Why use Moss with the Vercel AI SDK?

Required tools

Integration guide

Available tools

Read-only

Mutating (requires approval)

Configuration

Index binding

mossSearchTool options

​Why use Moss with the Vercel AI SDK?

​Required tools

​Integration guide

​Available tools

​Read-only

​Mutating (requires approval)

​Configuration

​Index binding

​mossSearchTool options

Why use Moss with the Vercel AI SDK?

Required tools

Integration guide

Available tools

Read-only

Mutating (requires approval)

Configuration

Index binding

mossSearchTool options