# tool_tavily

A RocketRide tool node that exposes [Tavily](https://tavily.com) 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

```json
{
  "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:

```bash
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.

---

<!-- 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 -->