Multi Engine Search for Agent

AI Agent search platform with 9 engines, Google 13 sub-types, vertical scene search, and intelligent auto/multi/extract modes. Designed for LLM and AI agent...

Security Scan

The skill's code, runtime instructions, and requested network access are consistent with a multi-engine search/ scraping client that requires a single NOVADA_API_KEY; nothing in the bundle indicates hidden exfiltration or unrelated privileges, though there is a small metadata mismatch to check.

Purpose & Capability

The name/description (multi-engine search for agents) matches the included code (novada_search.py, SDK, CLI, MCP server, LangChain integration) and the only service credential (NOVADA_API_KEY) is appropriate for a scraper/search API. The declared network target (scraperapi.novada.com) fits the stated purpose.

Instruction Scope

SKILL.md describes running the CLI/SDK/MCP server and enumerates limited filesystem permissions (tool files, samples, tests) and a single network endpoint. The runtime instructions do not ask the agent to read arbitrary home directories or unrelated credentials (they explicitly state they won't scan home directories and only support CLI flag, NOVADA_API_KEY, or local .env).

Install Mechanism

There is no install spec provided by the registry (instruction-only), and project files are included. References to pip (pip install novada-search) and github are normal project metadata. Nothing downloads arbitrary code from unknown URLs during install.

Credentials

The runtime requires a single NOVADA_API_KEY which is proportional to a scraper/search API. However there is an inconsistency: the registry summary at the top of the evaluation said 'Required env vars: none' while SKILL.md and _meta.json declare NOVADA_API_KEY as required. Confirm which registry metadata is authoritative before installing.

Persistence & Privilege

The skill does not request always: true or system-wide persistent privileges. It exposes an MCP stdio server and a LangChain tool (normal for this type of integration). It does not modify other skills or request global configs.

Assessment

This package appears to be a coherent multi-engine search client that needs one API key (NOVADA_API_KEY) to call Novada's scraper API. Before installing, verify the API key source (novada.com) and that you trust the provider; confirm the registry metadata mismatch (some registry metadata shows no required env but SKILL.md/_meta.json require NOVADA_API_KEY). Review novada_search.py for any additional outbound hosts or unexpected behavior (especially if you plan to run the MCP server). Consider running the package in an isolated environment or container, and avoid reusing high-privilege credentials (use a limited/billing-restricted key). If you have doubts about the upstream project, check the referenced repository (github.com/NovadaLabs/novada-search) and the provider's documentation before supplying your API key.

Novada Search v2.0

Multi-engine AI search — 9 engines, 13 Google types, 9 vertical scenes, smart agent modes. Powered by Novada Scraper API.

Get started in 30 seconds:

1. Get your free API key → novada.com
2. Set the key via environment or CLI: export NOVADA_API_KEY="your_key" (or pass --api-key $NOVADA_API_KEY)
3. Search: python3 {baseDir}/novada_search.py --query "coffee Berlin" --scene local

Agent-first + Human-friendly (Intelligent Distance)

This skill is optimized for agents first, then rendered for humans:

• Agent layer (machine logic)

  • Use --format agent-json.
  • Provides deterministic fields: engines_used, result_counts, duplicates_removed, unified_results, errors.
  • Best for planning, tool-chaining, re-ranking, and downstream automation.

• Human layer (readability)

  • Use --format enhanced or --format ranked.
  • Shows concise summaries, links, and ranked lists with less structural noise.

Recommended default contract for agent handoff:

python3 {baseDir}/novada_search.py --query "..." --scene news --format agent-json

If a human drags this skill to an agent, the agent should be able to clearly answer:

1. what this tool can do,
2. which mode to call (auto | multi | extract), and
3. which output format to consume (agent-json for logic).

SDK, MCP & Integrations (v1.0.8)

Python SDK

from novada_search import NovadaSearch

client = NovadaSearch(api_key="your_key")
result = client.search("coffee Berlin", scene="local")
result = client.search("buy shoes", mode="auto")
result = client.search("AI news", mode="multi", engines=["google", "bing"])
content = client.extract("https://example.com/article")

All SDK methods raise NovadaSearchError subclasses (not SystemExit), so agents can catch and recover.

MCP Server

python3 {baseDir}/novada_mcp_server.py

Tools: novada_search, novada_extract. Config example: mcp.json.

LangChain

from integrations.langchain_tool import NovadaSearchTool
tool = NovadaSearchTool(api_key="your_key")

Install via pip

pip install novada-search

agent-json enhanced fields

• response_time_ms
• search_metadata
• per-result domain
• per-result freshness

---

What’s New (P0) — Best-Answer First for Agents

• Unified Best Answer: agent-json now includes unified_results (top merged results across engines).
• Dedup that Agents Love: aggressive URL normalization + multi-engine merging; exposes duplicates_removed.
• Explainable Scoring: each unified result has score + agreement_count + domain + a short rationale.
• Regression Guardrail: added tests/ fixtures so ranking changes don’t silently degrade.

Troubleshooting (Read This)

• Novada may return HTTP 200 even on failure: the real error is in JSON data.code / data.msg. This CLI hard-checks it and will exit on non-success codes.
• Cloud/Vercel IPs may be blocked (402): validate from your production egress IP before shipping; request server-to-server allowlisting if needed.
• Local/Shopping default to fetch_mode=dynamic: slower, but higher hit rate for Maps/e-commerce pages.
• Debugging: add --verbose to see engine/type selection and execution path.

API Keys & Permissions

• NOVADA_API_KEY is required. Either export it (recommended for deployments) or pass --api-key per run.
• The CLI no longer scans home directories for secrets; it only checks CLI flag, NOVADA_API_KEY, or a local .env in the working folder.
• Declared permissions: filesystem (./*.py, ./*.md, ./samples/*) and network access to https://scraperapi.novada.com.

Real-World Example

Query: --query "dessert Düsseldorf" --scene local

Output:

🍰 Düsseldorf TOP 5 Dessert Shops

Rank	Shop	Rating	Reviews	Address
🥇	donecake	4.8★	3,500	Graf-Adolf-Straße 68
🥈	SugArt Factory	4.8★	423	Schloßstraße 76-78
🥉	Eiscafe Pia	4.7★	2,100	Kasernenstraße 1
4	Unbehaun Eis	4.6★	5,000	Aachener Str. 159
5	Aux Merveilleux de fred	4.6★	626	Kasernenstraße 15

Click any shop name to open in Google Maps. This is the default enhanced output — actionable links, no extra flags needed.

---

Architecture

  Layer 3  │  AI Agent    │  auto · multi · extract
  Layer 2  │  Scenes      │  shopping · local · jobs · academic · video · news · travel · finance · images
  Layer 1  │  Engines     │  google · bing · yahoo · duckduckgo · yandex · youtube · ebay · walmart · yelp
           │              │  + Google: shopping · local · news · scholar · jobs · flights · finance · patents · videos · images · play · lens

---

Layer 1 — Engines

9 Engines

Engine	Strength	Example
google	General + 13 sub-types	--engine google
bing	Web, news	--engine bing
yahoo	Finance	--engine yahoo
duckduckgo	Privacy	--engine duckduckgo
yandex	Russian web	--engine yandex
youtube	Video	--engine youtube
ebay	E-commerce	--engine ebay
walmart	US retail	--engine walmart
yelp	Local reviews	--engine yelp

13 Google Sub-Types

Use --engine google --google-type <type>:

Type	What it searches	Type	What it searches
search	Web (default)	shopping	Products & prices
local	Google Maps	news	Latest headlines
scholar	Academic papers	jobs	Job listings
flights	Airlines	finance	Stocks & markets
videos	Video content	images	Pictures
patents	IP / patents	play	Android apps
lens	Visual search

python3 {baseDir}/novada_search.py --query "MacBook Pro M4" --engine google --google-type shopping
python3 {baseDir}/novada_search.py --query "transformer attention" --engine google --google-type scholar
python3 {baseDir}/novada_search.py --query "python developer remote" --engine google --google-type jobs
python3 {baseDir}/novada_search.py --query "SFO to NRT" --engine google --google-type flights
python3 {baseDir}/novada_search.py --query "NVIDIA" --engine google --google-type finance

---

Layer 2 — Scenes

Scenes auto-combine the best engines for each use case. Use --scene <name>:

Scene	Engines combined	Use case	Status
📰 news	Google News + Bing	Multi-source news aggregation	✅ Available
🎓 academic	Google Scholar	Research papers & citations	✅ Available
💼 jobs	Google Jobs	Structured job listings	✅ Available
🎬 video	YouTube + Google Videos	Video tutorials & reviews	✅ Available
🖼️ images	Google Images	Image search	✅ Available
🛒 shopping	Google Shopping + eBay + Walmart	Cross-platform price comparison	🔜 Coming in v1.1
📍 local	Google Local + Yelp	Local business with ratings & maps	🔜 Coming in v1.1
✈️ travel	Google Flights	Flight search & pricing	🔜 Coming in v1.1
💰 finance	Google Finance + Yahoo	Stock data & market info	🔜 Coming in v1.1

python3 {baseDir}/novada_search.py --query "MacBook Pro" --scene shopping
python3 {baseDir}/novada_search.py --query "ramen Tokyo" --scene local
python3 {baseDir}/novada_search.py --query "react hooks tutorial" --scene video
python3 {baseDir}/novada_search.py --query "AI startup funding" --scene news

Scene Output Example — Shopping

Query: --query "AirPods Pro" --scene shopping --format agent-json

{
  "query": "AirPods Pro",
  "scene": "shopping",
  "engines_used": ["google:shopping", "ebay", "walmart"],
  "result_counts": { "shopping": 15, "organic": 6 },
  "shopping_results": [
    { "title": "Apple AirPods Pro 2nd Gen", "price": "$189.99", "seller": "Walmart", "rating": 4.8 },
    { "title": "Apple AirPods Pro 2 - New", "price": "$179.00", "seller": "eBay", "rating": 4.9 },
    { "title": "AirPods Pro (2nd generation)", "price": "$249.00", "seller": "Apple", "rating": 4.7 }
  ]
}

Shopping Scene Enhanced Output (Coming in v1.1)

⚠️ Shopping price comparison requires engine-specific data parsing that is being finalized. The price_comparison, lowest_price, and price_range fields will be available in v1.1 when Walmart and eBay result parsing is complete.

Local Scene Enhanced Output (Coming in v1.1)

⚠️ Local business enrichment (phone, hours, open_now) depends on Google Maps and Yelp data parsing that is being finalized for v1.1.

---

Layer 3 — Agent Modes

Use --mode <auto|multi|extract>:

Auto — Smart intent detection

Analyzes your query and auto-selects the best scene:

python3 {baseDir}/novada_search.py --query "buy Nike Air Max" --mode auto
#  → detects "shopping" → uses eBay + Walmart + Google Shopping

python3 {baseDir}/novada_search.py --query "best pizza near me" --mode auto
#  → detects "local" → uses Google Maps + Yelp

python3 {baseDir}/novada_search.py --query "latest AI news" --mode auto
#  → detects "news" → uses Google News + Bing

Intent keywords (EN/DE/ZH): buy/kaufen, near me/in der nähe, job/stelle, paper/forschung, video/tutorial, news/nachrichten, flight/flug, stock/aktie, image/bild

Multi — Parallel engines + dedup

Search multiple engines simultaneously, deduplicate by URL:

python3 {baseDir}/novada_search.py --query "web scraping tools" --mode multi --engines google,bing,duckduckgo

# Colon syntax for Google sub-types
python3 {baseDir}/novada_search.py --query "coffee maker" --mode multi --engines ebay,walmart,google:shopping

Extract — URL content for LLM

Pull clean text from any URL:

python3 {baseDir}/novada_search.py --url "https://example.com/article" --mode extract

Research — Search + Extract + Merge (Coming in v1.1)

⚠️ Research mode depends on the extract API which requires dynamic fetch mode. This feature will be fully available in v1.1.

python3 {baseDir}/novada_search.py --query "AI agent trends 2026" --mode research

SDK:

result = client.research("AI agent trends 2026", max_sources=5)
# result includes: unified_results + extracted_content[] + sources_extracted

---

Optional: AI Analysis (Bring Your Own LLM)

This tool focuses on search + structured results. If you want additional reasoning, use your own LLM API:

1. Run with structured output:

python3 {baseDir}/novada_search.py --query "..." --scene news --format agent-json > results.json

2. Feed results.json into your own LLM prompt (OpenAI/Claude/etc.) for summarization, ranking, or extraction.

This keeps Novada Search read-only and avoids bundling external AI keys into the skill.

Output Formats

Default is enhanced (clickable links). Override with --format <name>:

Format	Output type	Best for
enhanced (default)	Markdown + clickable Maps/website links	Daily use
ranked	Readable markdown with ratings	Quick overview
agent-json	Structured JSON for AI agents	LLM integration
table	Side-by-side comparison table	Comparing options
action-links	Shell open commands	Automation
raw	Full API response	Debugging

See samples/agent-json-example.json for a ready-to-copy agent-json payload with source_engine + confidence fields.

---

Full Command Reference

python3 {baseDir}/novada_search.py
  --query "search terms"                          # required (unless extract mode)
  --engine google|bing|yahoo|duckduckgo|yandex|youtube|ebay|walmart|yelp
  --google-type search|shopping|local|news|scholar|jobs|flights|finance|videos|images|patents|play|lens
  --scene shopping|local|jobs|academic|video|news|travel|finance|images
  --mode auto|multi|extract
  --engines google,bing,ebay                      # for multi mode (colon syntax: google:shopping)
  --url "https://..."                             # for extract mode
  --format enhanced|ranked|agent-json|table|action-links|raw
  --max-results 1-20                              # default: 10
  --fetch-mode static|dynamic                     # static = fast, dynamic = JS pages

Priority: --mode auto overrides everything. --scene overrides --engine. Direct --engine is the fallback.

---

vs Tavily

Feature	Novada Search	Tavily
Search engines	9	1
Google sub-types	13	0
Vertical scenes	9	0
Shopping (eBay+Walmart+Google)	v1.1	No
Local (Maps+Yelp)	v1.1	No
Video (YouTube)	Yes	No
Jobs / Academic / Travel	Yes	No
Multi-engine parallel	Yes	No
Auto intent detection	Yes	No
Content extraction	Yes	Yes
Agent JSON output	Yes	Yes

---

Get your API key → · GitHub · Powered by Novada Scraper API v2.0

---

中文版｜Novada Search v2.0

更新亮点（P0）— 面向 Agent 的“最佳答案优先”

• 统一最佳答案：agent-json 新增 unified_results（多引擎合并后的 Top 结果）。
• 强力去重：URL 归一 + 多引擎聚合；并输出 duplicates_removed。
• 可解释评分：每条 unified 结果带 score + agreement_count + domain + rationale（为什么排前）。
• 回归测试：新增 tests/ 固件，保证排序逻辑稳定不退化。

多引擎 AI 搜索平台——一次调用叠加 9 套主引擎、13 种 Google 类型、9 个垂直场景，并内置 auto / multi / extract 三层 Agent 模式。

快速上手

1. 在 novada.com 申请 NOVADA_API_KEY。
2. 用 export NOVADA_API_KEY="..." 或运行时 --api-key $NOVADA_API_KEY 注入（推荐显式传参，脚本不会再扫描个人目录）。
3. 运行示例：python3 {baseDir}/novada_search.py --query "coffee Berlin" --scene local。

常见问题｜踩坑

• Novada HTTP 常年 200，真实错误在 JSON data.code / data.msg，脚本已内建校验。
• 云服务器 / Vercel IP 可能被封（402），上线前先在目标 IP 做 Step 1.6 验证。
• local / shopping 场景默认 fetch_mode=dynamic，命中率更高但更慢。
• --verbose 可查看 engine/type 选择与节点评估。

真实案例

--query "dessert Düsseldorf" --scene local 会输出带点击链接的 Top 5 甜品店表格，可直接跳转 Google Maps。

架构分层

• Layer 1 引擎层：google / bing / yahoo / duckduckgo / yandex / youtube / ebay / walmart / yelp，Google 额外 13 个子类型（shopping/local/news/...）。
• Layer 2 场景层：shopping、local、jobs、academic、video、news、travel、finance、images，根据场景组合多引擎并定义合并策略。
• Layer 3 Agent 模式：auto（意图识别 → 场景）、multi（自选引擎并行去重）、extract（URL 正文抽取）。

指令参考

python3 {baseDir}/novada_search.py \
  --query "search" --scene news --format agent-json
python3 {baseDir}/novada_search.py \
  --mode multi --engines google:shopping,ebay,walmart --format table
python3 {baseDir}/novada_search.py \
  --mode extract --url "https://example.com/article"

输出格式

• enhanced：默认 Markdown，附地图/官网快速操作。
• ranked：排名 + 摘要。
• table：商品/本地商家对照表。
• agent-json / brave：结构化 JSON 供 LLM 食用（示例见 samples/agent-json-example.json）。
• action-links：生成 open "URL" 命令，方便自动化。
• raw：原始 API 回包。

vs Tavily 对比（精简版）

功能	Novada	Tavily
搜索引擎数量	9	1
Google 子类型	13	0
垂直场景	9	0
Shopping（eBay+Walmart+Google）	✅	❌
Local（Maps+Yelp）	✅	❌
多引擎并行	✅	❌
Auto intent	✅	❌
Extract API	✅	✅

实用建议

• 需要稳定输出 → 显式指定 --scene 或 --mode multi，避免 auto 误判。
• 需要被别的 Agent 调用 → 优先 --format agent-json，字段与 Tavily 兼容。
• 线上引用时建议直接传 --api-key 或在进程环境里 export（CLI 现仅读取 --api-key / NOVADA_API_KEY / 当前目录 .env）。
• 发布时请确保 registry metadata 与本包的 requiredEnv.NOVADA_API_KEY、permissions 保持一致（避免扫描器判定 metadata mismatch）。