nexo-web-search 0.2.1

Multi-provider web search client (Brave, Serper, etc.) for Nexo agents.
Documentation

nexo-web-search

Multi-provider web search router for Nexo — Brave / Tavily / DuckDuckGo / Perplexity behind one trait, with caching, sanitisation, and per-provider circuit breakers.

This crate is part of Nexo — a multi-agent Rust framework with a NATS event bus, pluggable LLM providers (MiniMax, Anthropic, OpenAI-compat, Gemini, DeepSeek), per-agent credentials, MCP support, and channel plugins for WhatsApp, Telegram, Email, and Browser (CDP).

What this crate does

  • SearchProvider trait — uniform search(args) -> Result<SearchResult> shape implemented by BraveProvider, TavilyProvider, DuckDuckGoProvider, PerplexityProvider. New providers just impl the trait.
  • WebSearchRouter — fanout / fallback orchestrator. provider: auto picks the first credentialed in priority order; explicit provider: overrides per call.
  • LRU result cache — TTL-based (cache_ttl_secs), query-keyed; cache hits don't count against per-provider rate limits.
  • Per-provider circuit breaker — uses nexo-resilience. A flapping provider opens its breaker; the router auto-skips to the next.
  • Result sanitisation — strips tracking params (utm_*, fbclid, …), HTML entities in titles, and oversized snippets.
  • Telemetry — nexo_web_search_calls_total{provider,result}, nexo_web_search_cache_total{provider,hit}, nexo_web_search_breaker_open_total{provider}, nexo_web_search_latency_ms{provider} histogram.
  • Used by the web_search agent tool (source) — agents call it through nexo-core's tool registry.

Public API

pub trait SearchProvider {
    async fn search(&self, args: WebSearchArgs) -> Result<SearchResult, SearchError>;
    fn name(&self) -> &'static str;
}

pub struct WebSearchRouter { /* … */ }

impl WebSearchRouter {
    pub fn new(providers: Vec<Arc<dyn SearchProvider>>) -> Self;
    pub async fn search(
        &self,
        args: WebSearchArgs,
        provider_hint: Option<&str>,
    ) -> Result<SearchResult, SearchError>;
}

Configuration

# config/agents.yaml — per-agent gating
agents:
  - id: ana
    web_search:
      enabled: true
      provider: auto              # auto | brave | tavily | duckduckgo | perplexity
      default_count: 5            # 1..=10
      cache_ttl_secs: 600         # 0 disables cache
      expand_default: false

API keys via env: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, PERPLEXITY_API_KEY. DuckDuckGo doesn't need a key.

Install

[dependencies]
nexo-web-search = "0.1"

Documentation for this crate

License

Licensed under either of:

at your option.