Tavily Search
Web search powered by Tavily API, optimized for AI agent consumption with structured, relevant results.
When to Use
- User asks for current/recent information beyond training cutoff
- Research tasks requiring multiple sources
- Fact-checking or verification
- Competitor analysis, market research
- News and updates on specific topics
- Finding documentation or resources
Quick Start
Basic search (5 results):
python3 scripts/search.py "your query here"
With options:
# Fewer results
python3 scripts/search.py "AI agents" --max-results 3
AI-generated answer
python3 scripts/search.py "what is OpenClaw" --answer
Advanced search (deeper crawling)
python3 scripts/search.py "casino bonuses" --depth advanced
Include images
python3 scripts/search.py "WordPress themes" --images
Raw JSON output
python3 scripts/search.py "n8n automation" --json
Parameters
- query (required): Search query string
--max-results N
: Number of results (1-10, default 5)--depth
: Search depth
basic
(default): Fast, good for most queriesadvanced
: Deeper crawling, more comprehensive
--answer
: Include AI-generated answer summary--images
: Include relevant image URLs--json
: Output raw JSON instead of formatted text
Output Structure
Formatted output includes:
- Query and response time
- AI-generated answer (if requested)
- Search results with:
- Title and URL
- Relevance score (0-1)
- Content snippet (truncated to 300 chars)
- Images (if requested)
JSON output provides full Tavily API response for programmatic use.
API Key Setup
The script looks for the Tavily API key in:
workspace/secrets/tavily_api_key
(OpenClaw workspace)secrets/tavily_api_key
(relative to current directory)TAVILY_API_KEY
environment variable
Current key is stored at:
workspace/secrets/tavily_api_key
Examples
Research task:
python3 scripts/search.py "WordPress plugin security best practices 2026" --max-results 5 --answer
Quick fact check:
python3 scripts/search.py "OpenClaw GitHub repository" --max-results 3
Competitive analysis:
python3 scripts/search.py "top casino affiliate sites" --depth advanced --max-results 10
News monitoring:
python3 scripts/search.py "AI agent frameworks January 2026" --answer
Tips
- Use specific queries for better results
--answer
is useful for summarization tasks--depth advanced
for comprehensive research (uses more API credits)- Relevance scores help identify best sources
--json
output is useful for parsing and processing results programmatically
