WebSearchSkill

Search the web using the Google Custom Search JSON API. The skill fetches more results than requested, scrapes each page, scores the extracted content, and returns only the highest-quality matches to the AI.

Class: WebSearchSkill

Tools: web_search (configurable via tool_name)

Env vars: GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_ENGINE_ID (legacy GOOGLE_SEARCH_CX is still accepted)

Multi-instance: yes — instance key combines search_engine_id and tool_name.

api_key

stringRequired

Google Custom Search API key. Falls back to the GOOGLE_SEARCH_API_KEY environment variable.

search_engine_id

stringRequired

Google Custom Search Engine ID. Falls back to the GOOGLE_SEARCH_ENGINE_ID environment variable (or the legacy GOOGLE_SEARCH_CX).

tool_name

string

Custom tool name for this Web Search instance (useful when registering multiple instances at once).

num_results

integerDefaults to 3

Number of high-quality results to return (range 1-10).

delay

numberDefaults to 0.5

Delay between scraping pages in seconds (minimum 0).

max_content_length

integerDefaults to 32768

Maximum total response size in characters (minimum 1000).

oversample_factor

numberDefaults to 2.5

How many extra results to fetch for quality filtering — e.g. 2.5 fetches 2.5× the requested num_results before scoring. Range 1.0-3.5.

min_quality_score

numberDefaults to 0.3

Minimum quality score (0–1) required to include a result.

no_results_message

string

Message returned when no quality results are found. Use {query} as a placeholder for the original search term.

safe_search

stringDefaults to medium

Safe-search level. One of "off", "medium", "high".

Example

1 import { AgentBase, WebSearchSkill } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4 agent.setPromptText('You are a helpful assistant.');
5 
6 await agent.addSkill(new WebSearchSkill({
7   num_results: 3,
8   safe_search: 'high',
9   min_quality_score: 0.4,
10 }));
11 
12 agent.run();

1	import { AgentBase, WebSearchSkill } from '@signalwire/sdk';
2
3	const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4	agent.setPromptText('You are a helpful assistant.');
5
6	await agent.addSkill(new WebSearchSkill({
7	num_results: 3,
8	safe_search: 'high',
9	min_quality_score: 0.4,
10	}));
11
12	agent.run();