# Send Tavily Web Search to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "tavily-web-search",
    "name": "Tavily Web Search",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/bert-builder/tavily",
    "canonicalUrl": "https://clawhub.ai/bert-builder/tavily",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/tavily-web-search",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tavily",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "references/api-reference.md",
      "scripts/tavily_search.py"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "tavily-web-search",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T09:33:00.656Z",
      "expiresAt": "2026-04-30T09:33:00.656Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tavily",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tavily",
        "contentDisposition": "attachment; filename=\"tavily-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "tavily-web-search"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/tavily-web-search"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/tavily-web-search",
    "downloadUrl": "https://openagent3.xyz/downloads/tavily-web-search",
    "agentUrl": "https://openagent3.xyz/skills/tavily-web-search/agent",
    "manifestUrl": "https://openagent3.xyz/skills/tavily-web-search/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/tavily-web-search/agent.md"
  }
}
```
## Documentation

### Overview

Tavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities.

Key capabilities:

AI-generated answer summaries from search results
Clean, structured results optimized for LLM processing
Fast (basic) and comprehensive (advanced) search modes
Domain filtering (include/exclude specific sources)
News-focused search for current events
Image search with relevant visual content
Raw content extraction for deeper analysis

### Architecture

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

### Basic Search

# Simple query with AI answer
scripts/tavily_search.py "What is quantum computing?"

# Multiple results
scripts/tavily_search.py "Python best practices" --max-results 10

### Advanced Search

# Comprehensive research mode
scripts/tavily_search.py "Climate change solutions" --depth advanced

# News-focused search
scripts/tavily_search.py "AI developments 2026" --topic news

### Domain Filtering

# Search only trusted domains
scripts/tavily_search.py "Python tutorials" \\
  --include-domains python.org docs.python.org realpython.com

# Exclude low-quality sources
scripts/tavily_search.py "How to code" \\
  --exclude-domains w3schools.com geeksforgeeks.org

### With Images

# Include relevant images
scripts/tavily_search.py "Eiffel Tower architecture" --images

### Basic vs Advanced

ModeSpeedCoverageUse Casebasic1-2sGoodQuick facts, simple queriesadvanced5-10sExcellentResearch, complex topics, comprehensive analysis

Decision tree:

Need a quick fact or definition? → Use basic
Researching a complex topic? → Use advanced
Need multiple perspectives? → Use advanced
Time-sensitive query? → Use basic

### General vs News

TopicTime RangeSourcesUse CasegeneralAll timeBroad webEvergreen content, tutorials, documentationnewsLast 7 daysNews sitesCurrent events, recent developments, breaking news

Decision tree:

Query contains "latest", "recent", "current", "today"? → Use news
Looking for historical or evergreen content? → Use general
Need up-to-date information? → Use news

### Option 1: Clawdbot Config (Recommended)

Add to your Clawdbot config:

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Access in scripts via Clawdbot's config system.

### Option 2: Environment Variable

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

Add to ~/.clawdbot/.env or your shell profile.

### Getting an API Key

Visit https://tavily.com
Sign up for an account
Navigate to your dashboard
Generate an API key (starts with tvly-)
Note your plan's rate limits and credit allocation

### 1. Research & Fact-Finding

# Comprehensive research with answer
scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

# Multiple authoritative sources
scripts/tavily_search.py "Best practices for REST API design" \\
  --max-results 10 \\
  --include-domains github.com microsoft.com google.com

### 2. Current Events

# Latest news
scripts/tavily_search.py "AI policy updates" --topic news

# Recent developments in a field
scripts/tavily_search.py "quantum computing breakthroughs" \\
  --topic news \\
  --depth advanced

### 3. Domain-Specific Research

# Academic sources only
scripts/tavily_search.py "machine learning algorithms" \\
  --include-domains arxiv.org scholar.google.com ieee.org

# Technical documentation
scripts/tavily_search.py "React hooks guide" \\
  --include-domains react.dev

### 4. Visual Research

# Gather visual references
scripts/tavily_search.py "modern web design trends" \\
  --images \\
  --max-results 10

### 5. Content Extraction

# Get raw HTML content for deeper analysis
scripts/tavily_search.py "Python async/await" \\
  --raw-content \\
  --max-results 5

### AI Answer

The AI-generated answer provides a concise summary synthesized from search results:

{
  "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..."
}

Use when:

Need a quick summary
Want synthesized information from multiple sources
Looking for a direct answer to a question

Skip when (--no-answer):

Only need source URLs
Want to form your own synthesis
Conserving API credits

### Structured Results

Each result includes:

title: Page title
url: Source URL
content: Extracted text snippet
score: Relevance score (0-1)
raw_content: Full HTML (if --raw-content enabled)

### Images

When --images is enabled, returns URLs of relevant images found during search.

### 1. Choose the Right Search Depth

Start with basic for most queries (faster, cheaper)
Escalate to advanced only when:

Initial results are insufficient
Topic is complex or nuanced
Need comprehensive coverage

### 2. Use Domain Filtering Strategically

Include domains for:

Academic research (.edu domains)
Official documentation (official project sites)
Trusted news sources
Known authoritative sources

Exclude domains for:

Known low-quality content farms
Irrelevant content types (Pinterest for non-visual queries)
Sites with paywalls or access restrictions

### 3. Optimize for Cost

Use basic depth as default
Limit max_results to what you'll actually use
Disable include_raw_content unless needed
Cache results locally for repeated queries

### 4. Handle Errors Gracefully

The script provides helpful error messages:

# Missing API key
Error: Tavily API key required
Setup: Set TAVILY_API_KEY environment variable or pass --api-key

# Package not installed
Error: tavily-python package not installed
To install: pip install tavily-python

### Programmatic Usage

from tavily_search import search

result = search(
    query="What is machine learning?",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

### JSON Output for Parsing

scripts/tavily_search.py "Python tutorials" --json > results.json

### Chaining with Other Tools

# Search and extract content
scripts/tavily_search.py "React documentation" --json | \\
  jq -r '.results[].url' | \\
  xargs -I {} curl -s {}

### Comparison with Other Search APIs

vs Brave Search:

✅ AI answer generation
✅ Raw content extraction
✅ Better domain filtering
❌ Slower than Brave
❌ Costs credits

vs Perplexity:

✅ More control over sources
✅ Raw content available
✅ Dedicated news mode
≈ Similar answer quality
≈ Similar speed

vs Google Custom Search:

✅ LLM-optimized results
✅ Answer generation
✅ Simpler API
❌ Smaller index
≈ Similar cost structure

### Script Won't Run

# Make executable
chmod +x scripts/tavily_search.py

# Check Python version (requires 3.6+)
python3 --version

# Install dependencies
pip install tavily-python

### API Key Issues

# Verify API key format (should start with tvly-)
echo $TAVILY_API_KEY

# Test with explicit key
scripts/tavily_search.py "test" --api-key "tvly-..."

### Rate Limit Errors

Check your plan's credit allocation at https://tavily.com
Reduce max_results to conserve credits
Use basic depth instead of advanced
Implement local caching for repeated queries

### Resources

See api-reference.md for:

Complete API parameter documentation
Response format specifications
Error handling details
Cost and rate limit information
Advanced usage examples

### Dependencies

Python 3.6+
tavily-python package (install: pip install tavily-python)
Valid Tavily API key

### Credits & Attribution

Tavily API: https://tavily.com
Python SDK: https://github.com/tavily-ai/tavily-python
Documentation: https://docs.tavily.com
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: bert-builder
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-23T09:33:00.656Z
- Expires at: 2026-04-30T09:33:00.656Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/tavily-web-search)
- [Send to Agent page](https://openagent3.xyz/skills/tavily-web-search/agent)
- [JSON manifest](https://openagent3.xyz/skills/tavily-web-search/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/tavily-web-search/agent.md)
- [Download page](https://openagent3.xyz/downloads/tavily-web-search)