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".

per_page_timeout
numberDefaults to 2.0

Maximum seconds to wait on a single page scrape. Minimum 0.1.

overall_deadline
numberDefaults to 10.0

Wall-clock budget in seconds for the entire tool call. In-flight scrapes are abandoned past this point so the response beats the kernel webhook timeout. Minimum 1.0.

parallel_scrape
booleanDefaults to true

Scrape all candidate pages concurrently (raced against the deadline) instead of sequentially.

snippets_only
booleanDefaults to false

Skip page scraping entirely and return Google CSE snippets only. The fastest mode (sub-second).

response_prefix
string

Optional text prepended (separated by a blank line) to every non-empty search result.

response_postfix
string

Optional text appended (separated by a blank line) to every non-empty search result.

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();