Web Search Tool

The amadev.web.search tool provides real-time web search without requiring any external API keys. It uses a two-strategy fallback chain to maximize result quality.

How It Works

Code

amadev.web.search(query)
        │
        ▼
┌──────────────────────────┐
│  Strategy 1: DuckDuckGo  │
│  HTML Search             │
│  html.duckduckgo.com     │
│  ┌────────────────────┐  │
│  │ Parse result__a   │  │
│  │ + result__snippet  │  │
│  │ Regex extraction   │  │
│  └────────────────────┘  │
│                          │
│  If < 3 results →        │
│  fallback to Strategy 2  │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│  Strategy 2: Wikipedia   │
│  OpenSearch API          │
│  en.wikipedia.org/w/     │
│  api.php?action=search   │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│  Deduplicate by URL      │
│  Cap at 10 results       │
└──────────────────────────┘

Implementation

Location: src/lib/tools/packs/general.ts

Strategy 1: DuckDuckGo HTML

Uses the DuckDuckGo HTML search endpoint (html.duckduckgo.com/html/), which returns real search results as HTML:

Code

const ddgRes = await fetch(
  `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
  { headers: { "User-Agent": "Mozilla/5.0 ..." }, signal: AbortSignal.timeout(8000) }
);

Parsing: Two-step regex extraction:

Primary: resultRegex — matches <a class="result__a" href="..."> + class="result__snippet" in a single pass
Fallback: If primary returns 0 results, simpler regex extracts just links and titles

URL handling: DuckDuckGo wraps URLs in redirect links (/l/?uddg=...). These are stripped via regex.

Strategy 2: Wikipedia

If DuckDuckGo returns fewer than 3 results, the tool additionally fetches from Wikipedia OpenSearch API:

Code

const wikiRes = await fetch(
  `https://en.wikipedia.org/w/api.php?action=opensearch&search=${q}&limit=5&format=json&origin=*`,
  { headers: { "User-Agent": "AmadevAI/1.0" }, signal: AbortSignal.timeout(5000) }
);

Deduplication

Results are deduplicated by URL before being returned (first occurrence wins).

Timeouts

DuckDuckGo: 8 seconds
Wikipedia: 5 seconds
Both wrapped in try/catch — failures silently fall through

Return Format

Code

{
  successful: true,
  data: {
    _ui_type: "professional-web",
    results: {
      answer: "Search results for 'latest AI news'",
      citations: [
        { title: "...", url: "...", snippet: "...", source: "Web" }
      ],
      organic_results: [
        { position: 1, title: "...", link: "...", snippet: "..." }
      ]
    }
  }
}

Capped at 10 results. citations has source attribution; organic_results has position numbering.

Using from Chat

Include the tool definition in your request:

Code

{
  "model": "groq/compound",
  "messages": [{ "role": "user", "content": "Cari berita terbaru AI" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "amadev.web.search",
      "description": "Search the web",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Search query" }
        },
        "required": ["query"]
      }
    }
  }]
}

Limitations

No API key required, but rate limits may apply from DuckDuckGo
HTML parsing is regex-based — fragile to DuckDuckGo layout changes
Wikipedia fallback gives encyclopedia results, not news
No image search, video search, or news-specific filtering