tavily-search

name	tavily-search
description	Web search using Tavily AI-powered search API. Returns AI-synthesized answers with citations and structured search results. Use when the user explicitly requests Tavily search, or when high-quality AI-synthesized answers with citations are needed for research, fact-checking, or comprehensive information gathering. Requires TAVILY_API_KEY.

Tavily Search

AI-powered web search that returns synthesized answers with citations and structured results.

When to Use

• User explicitly requests "use Tavily" or "search with Tavily"
• Research tasks requiring comprehensive, cited answers
• Fact-checking with source verification
• Alternative to Brave/Perplexity when specifically requested

Requirements

• Python 3.6+
• tavily-python package: pip install tavily-python
• TAVILY_API_KEY environment variable

Get your API key at: https://tavily.com

Script Location

The search script is located at skills/tavily-search/scripts/search.py relative to the application working directory. IMPORTANT: Always use the FULL path skills/tavily-search/scripts/search.py — do NOT shorten to scripts/search.py.

Quick Start

Basic search

python skills/tavily-search/scripts/search.py "latest AI developments"

Advanced search with more results

python skills/tavily-search/scripts/search.py "quantum computing breakthroughs" --max-results 10 --depth advanced

Text format output

python skills/tavily-search/scripts/search.py "climate change news" --format text

Usage

Command-line options

• query (required): Search query
• --max-results N: Maximum results (1-10, default: 5)
• --depth [basic|advanced]: Search depth (default: basic)
  • basic: Fast, general search
  • advanced: Deep, comprehensive search (slower, costs more)
• --no-answer: Exclude AI-generated answer
• --raw-content: Include full page content
• --format [json|text]: Output format (default: json)

Response format

Tavily returns:

• answer: AI-synthesized answer to the query
• results: Array of search results with:
  • title: Page title
  • url: Source URL
  • content: Relevant excerpt
  • score: Relevance score
• query: Original query
• response_time: API response time

Examples

Research query

python skills/tavily-search/scripts/search.py "What are the latest developments in quantum computing?" --depth advanced

Returns comprehensive answer with 5-10 cited sources.

Quick fact check

python skills/tavily-search/scripts/search.py "When was the Eiffel Tower built?" --max-results 3

Fast answer with minimal sources.

News search

python skills/tavily-search/scripts/search.py "breaking news today" --format text

Human-readable format with headlines and summaries.

Integration in OpenClaw

When called by the agent, run the script and parse the JSON output. IMPORTANT: The script path MUST be skills/tavily-search/scripts/search.py (full path from the application working directory).

import subprocess
import json

SEARCH_SCRIPT = "skills/tavily-search/scripts/search.py"

result = subprocess.run(
    ["python", SEARCH_SCRIPT, query, "--max-results", "5"],
    capture_output=True,
    text=True
)
response = json.loads(result.stdout)

Notes

• API key: Set TAVILY_API_KEY in environment or ~/.openclaw/.env
• Rate limits: Check Tavily pricing page for your plan's limits
• Search depth: Use basic for most queries; advanced for research
• Cost: Advanced search costs more credits per query

Troubleshooting

Module not found

pip install tavily-python

Missing API key

export TAVILY_API_KEY="tvly-xxx"

Permission denied

chmod +x skills/tavily-search/scripts/search.py