NativeVectorSearchSkill

Search documents by keyword scoring or through a remote search server. Supports two modes:

In-memory (TF-IDF) — supply a documents array in config; the skill tokenizes and indexes at startup (TypeScript-specific fast path).
Remote (network) — point remote_url at a search server and optionally name the index via index_name. Validated by the SSRF guard before each request; health check uses a 5-second timeout.

The Python SDK’s local-index parameters (index_file, build_index, backend, and the rest) are accepted so a Python configuration still loads, but this skill doesn’t use them; see Python compatibility parameters. The search_stats.backend value the skill writes to global data is remote with remote_url and memory otherwise.

Class: NativeVectorSearchSkill

Tools: search_knowledge (default — tool_name override supported)

Env vars: None

Multi-instance: yes (distinguished by tool_name + index_file)

Core Parameters

tool_name

stringDefaults to search_knowledge

Custom tool name for this skill instance. Required when registering multiple instances on the same agent.

remote_url

string

URL of a remote search server (network mode). Validated by the SSRF guard — private, loopback, and cloud-metadata endpoints are rejected. Every request, and every redirect it follows, is checked the same way. Credentials in the URL (https://user:password@host) are sent as basic auth and kept out of logs.

index_name

stringDefaults to default

Name of the index on a remote server. Only used with remote_url.

documents

object[]

In-memory array of documents to index (TypeScript-specific). Each entry has id (string), text (string), optional metadata (object), and optional tags (string[]).

Search Parameters

count

integerDefaults to 5

Number of search results to return (range 1-20).

similarity_threshold

numberDefaults to 0.0

Minimum similarity score for results (0.0 — no limit, 1.0 — exact match).

keyword_weight

number

In-memory mode only: how much keyword overlap counts against TF-IDF in the score (range 0.0-1.0, default 0.3). Has no effect with remote_url, where the server ranks results, and logs a warning there.

Content Parameters

global_tags

string[]Defaults to []

Tags added to every entry in documents when the skill indexes them at startup.

max_content_length

integerDefaults to 32768

Maximum total response size in characters (distributed across all results).

Response Parameters

no_results_message

stringDefaults to No information found for '{query}'

Message returned when no results match. Supports a {query} placeholder that is substituted with the user’s query text.

response_prefix

string

Text prepended to the search response.

response_postfix

string

Text appended to the search response.

response_format_callback

function

Optional callback to transform the final response. Receives { response, agent, query, results, args, count, skill } and must return a string.

description

stringDefaults to Search the knowledge base for information

Description of the search tool presented to the AI.

hints

string[]Defaults to []

Additional speech recognition hints for the tool.

Other Parameters

verbose

booleanDefaults to false

Enable verbose logging during indexing and search.

Python compatibility parameters

The skill accepts these parameters so a configuration written for the Python SDK still loads, but it doesn’t use them. The in-memory mode ranks with TF-IDF, and a remote server uses its own index and model.

Parameter	Effect in TypeScript
`index_file`	Part of the instance key only; no index file is read.
`build_index`, `source_dir`, `file_types`, `exclude_patterns`	None. No index is built from files.
`backend`, `connection_string`, `collection_name`, `overwrite`	None. The SQLite and pgvector backends aren’t available.
`model_name`	None.
`nlp_backend`, `query_nlp_backend`, `index_nlp_backend`	None.

Example — in-memory documents

import { AgentBase, NativeVectorSearchSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'kb-bot', route: '/kb' });
agent.setPromptText('Answer questions from the knowledge base.');
await agent.addSkill(new NativeVectorSearchSkill({
  tool_name: 'search_kb',
  documents: [
    { id: 'faq-1', text: 'Hours are 9am to 5pm Monday to Friday.', tags: ['hours'] },
    { id: 'faq-2', text: 'Returns are accepted within 30 days.', tags: ['returns'] },
  ],
  count: 3,
  similarity_threshold: 0.1,
  keyword_weight: 0.5,
}));
agent.run();

Example — remote server

await agent.addSkill(new NativeVectorSearchSkill({
  remote_url: 'https://search.internal.example.com',
  index_name: 'support-kb',
  count: 3,
  similarity_threshold: 0.4,
  tags: ['public'],
}));