Tavily
A RocketRide tool node that exposes Tavily real-time web search to an AI agent.
What it does
Gives an agent live web search. Agents invoke this node via the tool invoke channel; the node performs a search against the Tavily API and returns structured results containing titles, URLs, content snippets, and relevance scores.
The node has no pipeline input/output lanes (lanes is empty): it is consumed
exclusively by agent runtimes through the invoke capability. It is currently marked
experimental.
Implementation calls https://api.tavily.com/search over HTTPS using requests with
automatic retry (post_with_retry). Every result URL is validated with
validate_public_url before being returned, results pointing at non-public or unsafe
URLs are silently dropped. Request failures are returned to the agent as structured
{"success": false, "error": ...} payloads (including the HTTP status when available)
rather than raised as exceptions.
An API key is required: the pipeline fails at startup (beginGlobal raises) if no
key is found in the node config or the environment.
Configuration
| Field | Type | Description |
|---|---|---|
apikey | string | Default empty. Tavily API key (from https://tavily.com) |
maxResults | integer | Default 5. Maximum number of search results to return (1-20) |
searchDepth | string | Default "advanced". Tavily search depth |
topic | string | Default "general". Search topic category |
The default profile ships with maxResults: 5, searchDepth: advanced,
topic: general, and an empty apikey.
Available tools
tavily
Search the web in real time. Provide a natural language query to find relevant, current web pages.
| Tool | Description |
|---|---|---|
| tavily | Search the web in real time using Tavily. Provide a natural language query to find relevant, current web pages. Returns structured results with title, URL, content snippet, and relevance score. |
Per-call values override the node config; invalid values silently fall back to the
configured defaults. time_range, include_domains, and exclude_domains are omitted
from the request when absent or invalid.
Output
{
"success": true,
"query": "...",
"num_results": 3,
"results": [
{
"title": "...",
"url": "https://...",
"content": "...",
"score": 0.97,
"published_date": "..."
}
]
}
On failure, success is false, results is empty, and error describes the problem
(missing query, HTTP error with status code, non-JSON response, or unexpected payload).
Authentication
Provide the Tavily API key either:
- in the node config field API Key (
apikey), or - via the environment variable:
ROCKETRIDE_TAVILY_KEY=tvly-...
The config field takes precedence; the env var is used only when the field is blank.
Pipeline env vars must be ROCKETRIDE_-prefixed, only those are substituted by the
engine.
Schema
| Field | Type | Description | Default |
|---|---|---|---|
tool_tavily.apikey | string | API Key Tavily API key (from https://tavily.com) | "" |
tool_tavily.maxResults | integer | Max Results Maximum number of search results to return (1-20) | 5 |
tool_tavily.searchDepth | string | Search Depth Tavily search depth | "advanced" |
tool_tavily.topic | string | Topic Search topic category | "general" |
Dependencies
requests