> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# tool_tavily

A RocketRide tool node that gives an agent live web-search results from Tavily. Pick it when an agent needs current web pages in a compact search result, rather than a general HTTP request or a static knowledge source.

## About Tavily

Tavily provides search and research APIs intended for AI applications. Its search response combines result URLs, titles, snippets, and relevance information for programmatic use.

## What it does

The node has no data lanes and registers one real-time search function. It sends the configured defaults and any supported per-call overrides to the Tavily search endpoint, then returns structured result records. Use it for retrieval during an agent run; it is experimental, so callers should handle service errors rather than assuming a search always succeeds.

## As a tool

The prefix defaults to `tavily`, so the registered function is `tavily.tavily`.

| Function | Description |
|---|---|
| `tavily.tavily` | Search the web with a required natural-language `query`. |

Optional arguments are `max_results` (1–20), `search_depth` (`basic` or `advanced`), `topic` (`general`, `news`, or `finance`), `time_range` (`day`, `week`, `month`, or `year`), and `include_domains` / `exclude_domains`. A successful response includes `success`, the query, `num_results`, and `results`; a failed request returns `success: false` with an `error` string.

## Configuration

Set the API key, then use the defaults as a sensible baseline. Call-level arguments override the configured result count, depth, and topic when a specific question needs a different search.

### Max Results

The configured count must be 1–20 and defaults to 5. Increase it when the agent must compare multiple sources; keep it small for focused questions so the agent receives less irrelevant context.

### Search Depth and Topic

`advanced` is the default depth, while `basic` is available for a simpler search. The topic default is `general`; choose `news` or `finance` when that category better matches the request. These settings remain defaults only—per-call values take precedence.

## Authentication

Set `apikey` to a Tavily API key. An empty key prevents the node from performing a search.

## Upstream docs

- [Tavily API documentation](https://docs.tavily.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_tavily.apikey` | `string` | **API Key**<br/>Tavily API key (from https://tavily.com) | `""` |
| `tool_tavily.maxResults` | `integer` | **Max Results**<br/>Maximum number of search results to return (1-20) | `5` |
| `tool_tavily.searchDepth` | `string` | **Search Depth**<br/>Tavily search depth | `"advanced"` |
| `tool_tavily.topic` | `string` | **Topic**<br/>Search topic category | `"general"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_tavily)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
