Web search & research tools

Hania offers three complementary search tools. The agent picks per-query options (count, freshness, depth, topic, etc.) automatically - you just decide which tool(s) to enable.

• Brave Search (brave) - general live web search. Find current pages, facts, and (with result_type=news) recent news. Requires a Brave API key. Returns ranked links with snippets.
• Tavily (tavily) - AI-optimized research. search returns ranked results plus a synthesized answer (great for "what's the latest on X"); extract pulls the clean readable text of specific URLs (great for "read this page"). Requires a Tavily key (free tier available).
• DuckDuckGo Instant Answers (duckduckgo) - free, no key. Quick definitions and encyclopedic facts only; not a general web search - use Brave or Tavily for that.

Built-in web search, no setup

Look in your tool catalog for a Web Search built-in. If it is there, you can switch it on in one click and assign it to a bot like any other built-in, with no key to enter and nothing to configure. The agent can then search the live web right away.

If you do not see it in your catalog, pick one of the tools below and connect it with your own key. Those tools also give you finer control over the search itself; the built-in just keeps things simple.

Choosing a tool

• Quick definition or encyclopedic fact → DuckDuckGo (free).
• General web or news search → Brave.
• Research with a summary, or reading specific pages → Tavily.

A common research pattern: a Brave or Tavily search to find sources → Tavily extract (or the fetch-webpage tool) to read them.

Costs & limits

• Brave - free tier is metered (~$5/mo credit) and rate-limited to 1 request/second; bursts return a "rate limited" error. Paid plans bill per 1k requests.
• Tavily - free tier is 1,000 credits/month (basic search = 1 credit, advanced = 2; URL extraction = 1 credit per 5 URLs).
• DuckDuckGo - free and unlimited, but limited in capability (instant answers only).

Brave Search

Live web search. Configuration is a single field - your Brave Search API subscription token (starts with BSA), sent as the X-Subscription-Token header, stored encrypted and never shown again.

Get a key: go to api-dashboard.search.brave.com → sign in → subscribe to a plan (the entry plan includes a small monthly credit) → under API Keys, copy the subscription token (BSA…). Keep request volume to ≤1/sec on the free tier.

One action - search - with these parameters (the agent sets them):

• query (required) - the search query.
• count - 1–20 (default 5).
• freshness - pd / pw / pm / py (past day / week / month / year).
• result_type - web or news (news returns recent news articles).
• country - 2-letter code, e.g. us.
• safesearch - off / moderate / strict (default moderate).

Returns {type, results:[{title, url, description, age}]} (a projected shape, not raw Brave JSON).

Tavily

AI-optimized search and extraction. Configuration is a single field - your Tavily API key (starts with tvly-), stored encrypted and never shown again.

Get a key: go to app.tavily.com → sign up (no card for the free tier) → API Keys → copy your key (tvly-…). The free tier gives 1,000 credits/month.

Two actions (the agent picks one and its parameters):

• search - query (required), search_depth (basic / advanced), topic (general / news / finance), time_range (day / week / month / year), max_results (1–20), include_domains / exclude_domains. Returns {answer, results:[{title, url, content, score, published_date}]} - always with a synthesized answer.
• extract - urls (required, ≤20), optional query to rerank. Returns {results:[{url, raw_content}], failed_results} as clean markdown.

DuckDuckGo Instant Answers

Free and keyless - nothing to set up; it's always available to every bot. One action - search with a query - returning {abstract, source, url, answer, definition, related_topics:[{text, url}]}. It provides definitions and encyclopedic facts only, not general web search; use Brave or Tavily for real searches.

Classification & lifecycle

All three are read-only, so the destructive / sends-data-externally classification flags don't apply (they ship unset). Each is post-call-hook eligible - e.g. "after the call, look up the latest on the topic and email a summary."