AgentsSkills

WebSearchSkill

View as MarkdownOpen in Claude

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.

stringDefaults to medium

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

Example

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