Moss - Real-time Semantic Search for Conversational AI

Integrate Moss semantic search into a VAPI voice agent using the vapi-moss package. This setup lets your conversational AI perform sub-10ms knowledge base lookups through VAPI’s Custom Knowledge Base webhook, so your agent can answer questions instantly during live calls.

Note: For a complete FastAPI server example, see the vapi-moss app.

Why use Moss with VAPI?

VAPI’s Custom Knowledge Base webhook fires on every user turn, expecting fast document retrieval. Moss responds in under 10ms, keeping voice interactions natural and fluid without added latency from traditional RAG pipelines.

Required tools

Moss account with project credentials
VAPI account with a Conversational AI agent
Python 3.10+

Integration guide

Installation

pip install vapi-moss

Environment setup

Create a .env file in your project root with your credentials.

.env

# Moss Credentials
MOSS_PROJECT_ID=your_project_id
MOSS_PROJECT_KEY=your_project_key
MOSS_INDEX_NAME=your_index_name

# VAPI Webhook Secret (from your VAPI Knowledge Base config)
VAPI_WEBHOOK_SECRET=your_webhook_secret

Search and verify signatures

Use MossVapiSearch to query your index and verify_vapi_signature to validate incoming webhook requests.

from vapi_moss import MossVapiSearch, verify_vapi_signature

# Initialize the search client
search = MossVapiSearch(
    index_name="my-faq-index",
    top_k=5,
    alpha=0.8,
)

# Load the index at startup
await search.load_index()

# Search
result = await search.search("How do I return an item?")
print(result.documents)    # [{"content": "...", "similarity": 0.92}, ...]
print(result.time_taken_ms)  # 3

# Verify webhook signatures
is_valid = verify_vapi_signature(
    raw_body=request_bytes,
    signature_header=headers["x-vapi-signature"],
    secret="your-webhook-secret",
)

Configure VAPI

In your VAPI dashboard:

Navigate to your agent’s settings
Under Knowledge Base, select Custom Knowledge Base
Set the webhook URL to your server endpoint (e.g., https://your-server.com/webhook)
Add your webhook secret to enable signature verification

Configuration

MossVapiSearch

Parameter	Type	Default	Description
`project_id`	`str`	`None`	Your Moss Project ID. Falls back to `MOSS_PROJECT_ID` env var.
`project_key`	`str`	`None`	Your Moss Project Key. Falls back to `MOSS_PROJECT_KEY` env var.
`index_name`	`str`	Required	The name of the Moss index to query.
`top_k`	`int`	`5`	Number of results to retrieve per query.
`alpha`	`float`	`0.8`	Hybrid search weighting. `0.0` = keyword only, `1.0` = semantic only.

Voice & Real-time

AI Frameworks

Developer Tools

VAPI

Why use Moss with VAPI?

Required tools

Integration guide

Configuration

MossVapiSearch

​Why use Moss with VAPI?

​Required tools

​Integration guide

​Configuration

​MossVapiSearch

Why use Moss with VAPI?

Required tools

Integration guide

Configuration

MossVapiSearch