feat: add Tavily as optional search backend in WebSearchTool

package.json

@@ -112,6 +112,7 @@
     "ws": "^8.20.0",
     "xss": "^1.0.15",
     "yaml": "^2.8.3",
+    "@tavily/core": "^0.6.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {

src/tools/WebSearchTool/WebSearchTool.ts

@@ -4,6 +4,7 @@ import { buildTool, type ToolDef } from '../../Tool.js'
 import { lazySchema } from '../../utils/lazySchema.js'
 import { logError } from '../../utils/log.js'
 import { getWebSearchPrompt, WEB_SEARCH_TOOL_NAME } from './prompt.js'
+import { tavily } from '@tavily/core'
 import {
   getToolUseSummary,
   renderToolResultMessage,
@@ -93,6 +94,38 @@ async function searchSearXNG(
   }
 }
 
+/**
+ * 使用 Tavily 云搜索
+ */
+async function searchTavily(
+  query: string
+): Promise<Array<{ title: string; url: string; snippet?: string }>> {
+  try {
+    const apiKey = process.env.TAVILY_API_KEY
+    if (!apiKey) {
+      throw new Error('TAVILY_API_KEY is not set')
+    }
+
+    const client = tavily({ apiKey })
+    const response = await client.search(query, {
+      maxResults: 10,
+      searchDepth: 'basic',
+      topic: 'general',
+    })
+
+    return (response.results || []).map((r: any) => ({
+      title: r.title,
+      url: r.url,
+      snippet: r.content,
+    }))
+  } catch (error) {
+    logError('Tavily search failed', error)
+    throw new Error(
+      `Tavily search failed: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+}
+
 /**
  * 文本清洗
  */
@@ -123,7 +156,7 @@ function cleanSearchResult(result: any) {
 
 export const WebSearchTool = buildTool({
   name: WEB_SEARCH_TOOL_NAME,
-  description: 'Search the web using local SearXNG',
+  description: 'Search the web using local SearXNG or Tavily (when TAVILY_API_KEY is set)',
   shouldDefer: true,
 
   getToolUseSummary,
@@ -201,7 +234,10 @@ export const WebSearchTool = buildTool({
         })
       }
 
-      const results = await searchSearXNG(input.query)
+      const useTavily = !!process.env.TAVILY_API_KEY
+      const results = useTavily
+        ? await searchTavily(input.query)
+        : await searchSearXNG(input.query)
 
       const cleaned = results.map(r => ({
         ...r,

src/tools/WebSearchTool/__tests__/WebSearchTool.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe } from 'bun:test'
+import { test, expect, describe, beforeEach, afterEach, mock } from 'bun:test'
 import { WebSearchTool } from '../WebSearchTool'
 
 describe('WebSearchTool', () => {
@@ -224,4 +224,60 @@ describe('WebSearchTool', () => {
       expect(result.data.durationSeconds).toBeGreaterThan(0)
     }, 60000)
   })
+
+  describe('Tavily Integration', () => {
+    let originalTavilyKey: string | undefined
+
+    beforeEach(() => {
+      originalTavilyKey = process.env.TAVILY_API_KEY
+    })
+
+    afterEach(() => {
+      if (originalTavilyKey !== undefined) {
+        process.env.TAVILY_API_KEY = originalTavilyKey
+      } else {
+        delete process.env.TAVILY_API_KEY
+      }
+    })
+
+    test('should use SearXNG when TAVILY_API_KEY is not set', async () => {
+      delete process.env.TAVILY_API_KEY
+
+      const result = await WebSearchTool.call(
+        { query: 'test query' },
+        {},
+        () => {},
+        null
+      )
+
+      expect(result).toBeDefined()
+      expect(result.data.query).toBe('test query')
+      expect(Array.isArray(result.data.results)).toBe(true)
+    }, 60000)
+
+    test('should use Tavily when TAVILY_API_KEY is set', async () => {
+      process.env.TAVILY_API_KEY = 'tvly-test-key'
+
+      const result = await WebSearchTool.call(
+        { query: 'test tavily query' },
+        {},
+        () => {},
+        null
+      )
+
+      // With a fake key, Tavily will fail and we should get an error result
+      expect(result).toBeDefined()
+      expect(result.data.query).toBe('test tavily query')
+      expect(Array.isArray(result.data.results)).toBe(true)
+      // The result should contain an error since the API key is invalid
+      const hasError = result.data.results.some(
+        r => typeof r === 'string' && r.includes('Error')
+      )
+      expect(hasError).toBe(true)
+    }, 60000)
+
+    test('should include Tavily in description when key is set', () => {
+      expect(WebSearchTool.description).toContain('Tavily')
+    })
+  })
 })

src/tools/WebSearchTool/prompt.ts

@@ -6,14 +6,15 @@ export function getWebSearchPrompt(): string {
   const currentMonthYear = getLocalMonthYear()
 
   return `
-- Allows VersperClaw to search the web using a local SearXNG search engine and use the results to inform responses
+- Allows VersperClaw to search the web using a local SearXNG search engine or Tavily cloud search (when TAVILY_API_KEY is configured) and use the results to inform responses
 - Provides up-to-date information for current events, technical documentation, and recent data
 - Returns structured search results including titles, URLs, and snippets
 - Works with all AI providers including local models
 - Designed for high-recall search to support reasoning and retrieval-augmented generation (RAG)
 
 Search Strategy:
-  - Uses SearXNG metasearch engine (aggregates multiple sources)
+  - Default: Uses SearXNG metasearch engine (aggregates multiple sources)
+  - When TAVILY_API_KEY is set: Uses Tavily cloud search API for high-quality, LLM-optimized results
   - Results may vary in quality; prioritize relevance and credibility
   - If results are weak or empty, try rephrasing the query
   - Prefer more specific queries when possible (add keywords, version numbers, or context)