Tavily AI Search: Add Real-Time Web Intelligence to Your OpenClaw Agents

2026-03-03 2395 words 12 minutes

Contents

Tavily is an AI-powered search API that does something most search engines don’t: it synthesizes answers from multiple sources instead of just returning links.

This article walks you through setting up Tavily for OpenClaw agents, explains the pricing (spoiler: free tier requires no credit card), and shows real-world examples.

What Is Tavily?

Tavily is a production-grade search API trusted by 1M+ developers. Unlike traditional search engines, Tavily combines:

Real-time web crawling — Access to billions of indexed pages
AI reasoning — Synthesizes an answer from multiple sources
Content extraction — Pulls relevant snippets and context
Security layers — Blocks PII leakage, prompt injection, malicious sources

Key difference from Brave Search API:

Feature	Tavily	Brave Search
AI Answer	✅ Synthesized from sources	❌ Just links/snippets
Speed	~180-500ms (p50)	~200-300ms
Response Depth	5-10 relevant sources + reasoning	Simple list of results
News Filtering	✅ Yes (topic: news)	✅ Yes
Free Tier	✅ 1,000 credits/mo	Limited trial, then paid
API Key Required	✅ Yes (free)	✅ Yes (freemium)
Use Case	Research, synthesis, agents	General purpose search

When to use Tavily:

Research and knowledge synthesis
Agent decision-making (needs reasoned answers)
Deep technical queries
When you need AI-powered analysis of sources
Building AI agents that need context, not just links

When to use Brave Search:

General web searches
Speed is the priority
You prefer traditional search results format
Already integrated with other Brave ecosystem tools

Getting Your Free API Key (No Credit Card Needed)

Tavily’s Researcher tier is completely free with no credit card required.

Go to app.tavily.com
Click “Sign Up” (top right)
Enter your email and create a password
That’s it — no card needed, no verification email required (instant signup)

Step 2: Find Your API Key

Once signed in:

Click your profile icon (top right) → “API Keys” (or go to app.tavily.com/api)
You’ll see your API key (looks like: tvly_xxxxxxxxxxxxxxxxxxxxx)
Copy it — you’ll use this in OpenClaw

Step 3: Store Your API Key

You have three options for storing the API key. Each has tradeoffs:

Option A: Environment Variable (Best for Development)

export TAVILY_API_KEY="tvly_xxxxxxxxxxxxxxxxxxxxx"

Pros: Simple, works immediately, portable
Cons: Lost when terminal closes, not persistent
Use when: Testing, one-off scripts, local development

Option B: OpenClaw `.env` File (Recommended for Long-Term)

echo 'TAVILY_API_KEY="tvly_xxxxxxxxxxxxxxxxxxxxx"' >> ~/.openclaw/workspace/.env

Pros: Persistent across sessions, OpenClaw-aware, auto-loaded
Cons: Stored in plain text (keep permissions strict)
Use when: Regular development, agents that need persistent keys

Verify it loaded:

source ~/.openclaw/workspace/.env
echo $TAVILY_API_KEY  # Should print your key

Option C: System Secrets Manager (Best for Production)

If you’re running OpenClaw on a server, use your OS secrets manager:

Linux (systemd-based):

# Store in systemd user secrets
systemctl --user set-environment TAVILY_API_KEY="tvly_xxxxxxxxxxxxxxxxxxxxx"

macOS (Keychain):

# Store in macOS Keychain
security add-generic-password -a openclaw -s tavily-api-key -w "tvly_xxxxxxxxxxxxxxxxxxxxx"

Docker (if containerized):

# Use Docker secrets or pass via --env-file
docker run --env-file ~/.openclaw/workspace/.env openclaw

Pros: Secure, OS-managed, encrypted
Cons: Platform-specific, requires setup
Use when: Production agents, shared systems, security-sensitive

Security Best Practices

Never commit API keys to git:

# Add to .gitignore
echo ".env" >> ~/.openclaw/workspace/.gitignore

Restrict file permissions:
```
chmod 600 ~/.openclaw/workspace/.env
```
Rotate keys regularly:
- Go to app.tavily.com/api
- Generate a new key
- Update your .env
- Delete the old key
Use separate keys per environment:
- Development key (test freely)
- Production key (limited usage alerts)

Pricing & Limits

Free Tier: “Researcher”

1,000 API credits/month
No credit card required
Email support
Good for development, learning, side projects

What’s a “credit”?

Each API call costs 1 credit (regardless of query length)
1,000 searches/month = ~33/day
Enough for most hobby projects and testing

Pay-As-You-Go

$0.008 per credit (after free tier exhausted)
Flexible — use what you need, pay only for usage
Scale up without long-term commitment

Project Tier

$12-24/month (slide to adjust)
4,000 API credits/month (higher rate limits)
Good for production use

Enterprise

Custom pricing
Custom rate limits
Dedicated support & SLAs

Bottom line: You can build and test for free indefinitely. Move to pay-as-you-go when you’re ready to scale.

Understanding OpenClaw Skills

OpenClaw uses a skill framework to organize integrations. Think of a skill as a packaged tool with:

SKILL.md — Documentation and API reference
Python scripts — CLI tools and libraries
Resources — Config files, references, examples

The tavily-search skill comes pre-built in your workspace. You can:

Use it as-is (easiest)
Customize it for your needs (intermediate)
Build your own skills using the skill-creator framework (advanced)

Setting Up with OpenClaw

OpenClaw includes a pre-built tavily-search skill. Here’s how to use it:

Quick Test via cURL

curl -X POST http://localhost:8002/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI breakthroughs 2026",
    "search_depth": "basic",
    "max_results": 5
  }'

Python Integration

from tavily_search import TavilySearchClient

# Initialize client (reads TAVILY_API_KEY from env)
client = TavilySearchClient()

# Basic search (fast, 2 sec)
response = client.search(
    query="how does quantum computing work",
    search_depth="basic"
)

print(response["answer"])     # AI-synthesized answer
for result in response["results"]:
    print(f"- {result['title']}: {result['url']}")

# Advanced search (comprehensive, 2-3 sec)
response = client.search(
    query="kubernetes deployment strategies",
    search_depth="advanced",
    max_results=10
)

# News search
response = client.search(
    query="latest AI safety developments",
    topic="news",
    search_depth="basic"
)

CLI Usage

# Basic search
python scripts/tavily_client.py "python asyncio tutorial"

# Advanced with 10 results
python scripts/tavily_client.py "machine learning trends" \
  --depth advanced \
  --max-results 10

# News search
python scripts/tavily_client.py "AI regulation" \
  --topic news

# Quick search (fastest)
python scripts/tavily_client.py "what is WebSocket" --quick

# JSON output
python scripts/tavily_client.py "latest tech news" --json

Real-World Integration Examples

Example 1: Research Assistant for Blog Posts

from tavily_search import TavilySearchClient

client = TavilySearchClient()

# Agent gathers sources for a blog post
response = client.search(
    query="best practices for error handling in Rust",
    search_depth="advanced",
    max_results=8
)

print(f"**AI Summary:** {response['answer']}\n")
print("**Sources:**")
for result in response["results"]:
    print(f"- {result['title']}")
    print(f"  {result['url']}")
    print(f"  Relevance: {result['score']*100:.0f}%\n")

Example 2: Decision Support in Agents

# Agent needs to decide on a technology
research = client.search(
    query="AWS vs GCP for machine learning in 2026",
    search_depth="advanced"
)

# Agent uses synthesized answer + sources to make informed decision
decision = f"""
Based on latest research:
{research['answer']}

Supporting sources: {len(research['results'])} authoritative sources retrieved
"""

Example 3: Current Events Feed

# Monitor latest news in a domain
response = client.search(
    query="AI regulation updates February 2026",
    topic="news",
    search_depth="basic",
    max_results=5
)

# Auto-post to Slack/Discord when new news arrives
for result in response["results"]:
    notify(f"📰 {result['title']}\n{result['url']}")

Example 4: Tavily for Agent Decision-Making

# Agent researching a technology decision
response = client.search(
    query="FastAPI vs Django for REST APIs in 2026",
    search_depth="advanced",
    max_results=10
)

# Extract synthesized comparison from answer
comparison = response["answer"]
sources = [r["url"] for r in response["results"]]

# Agent uses reasoning to make decision
agent_decision = f"""
Based on current best practices:
{comparison}

References: {', '.join(sources[:3])}...
"""

Response Structure

Every Tavily search returns:

{
  "query": "your search query",
  "answer": "AI-synthesized answer from sources",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com",
      "content": "Article snippet / relevant excerpt",
      "score": 0.95
    }
  ],
  "response_time": 1.23
}

Fields explained:

answer — AI reasoning across all sources (unique to Tavily)
content — Extracted snippet relevant to your query
score — Relevance score (0-1, higher = more relevant)
response_time — Seconds to get answer (plan for ~200-500ms)

Building and Customizing Skills with skill-creator

The skill-creator framework is how OpenClaw manages integrated tools. It ensures:

✅ Proper documentation structure (SKILL.md)
✅ Consistent packaging and versioning
✅ CLI tools + Python libraries together
✅ Easy distribution and updates

How Skills Are Structured

Every OpenClaw skill has this layout:

~/.openclaw/workspace/skills/tavily-search/
├── SKILL.md                    # Public documentation
├── tavily-search.skill         # Skill metadata (YAML)
├── scripts/
│   └── tavily_client.py        # CLI tool + Python library
├── references/
│   ├── depth-comparison.md     # Usage guides
│   └── python-examples.md      # Code samples
└── resources/
    └── config-example.json     # Template configs

Using the Pre-Built tavily-search Skill

The skill is already built and ready. You can use it immediately:

# List available skills
ls ~/.openclaw/workspace/skills/

# Check if tavily-search is there
ls ~/.openclaw/workspace/skills/tavily-search/

# Use the skill
python ~/.openclaw/workspace/skills/tavily-search/scripts/tavily_client.py "your query"

Customizing the tavily-search Skill

If you want to modify the skill (add features, change behavior), edit these files:

1. Modify the Python library:

nano ~/.openclaw/workspace/skills/tavily-search/scripts/tavily_client.py

Examples of customizations:

Add caching layer (avoid duplicate searches)
Change response formatting
Add logging/monitoring
Integrate with external tools (Slack, Discord)

2. Update the documentation:

nano ~/.openclaw/workspace/skills/tavily-search/SKILL.md

Add sections like:

Custom examples for your use case
Performance benchmarks
Integration patterns with other skills

3. Add your own references:

# Create a new reference document
touch ~/.openclaw/workspace/skills/tavily-search/references/my-use-cases.md

After changes, test locally:

# Test the modified skill
python ~/.openclaw/workspace/skills/tavily-search/scripts/tavily_client.py \
  "test query" \
  --depth advanced \
  --max-results 5

Creating a New Skill from Scratch

If you want to build a new skill (not just customize tavily-search), use the skill-creator framework:

Step 1: Initialize the Skill

cd ~/.openclaw/workspace/skills/

# Run the skill-creator framework
python /path/to/skill-creator/init_skill.py \
  --name my-awesome-skill \
  --description "What this skill does"

This creates the directory structure:

my-awesome-skill/
├── SKILL.md           # (empty, you fill it)
├── my-awesome-skill.skill
├── scripts/
│   └── client.py      # (starter code)
└── references/
    └── examples.md

Step 2: Write the Skill Documentation (SKILL.md)

The SKILL.md is the public API. It tells users:

What the skill does
How to use it (examples)
All available commands and parameters
Response formats

Example structure:

---
name: my-awesome-skill
description: "One-line description"
---

# My Awesome Skill

## Overview
Multi-line explanation...

## Quick Start
```bash
python scripts/client.py "example"

API Reference

Endpoint: /search

Parameters: query, limit
Returns: …

Examples

…


#### Step 3: Write the Python Implementation

Edit `scripts/client.py`:

```python
import argparse
import requests

class MyAwesomeClient:
    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv("MY_API_KEY")
        self.base_url = "https://api.example.com"
    
    def search(self, query, max_results=5):
        """Core functionality"""
        response = requests.post(
            f"{self.base_url}/search",
            json={"query": query, "limit": max_results},
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
        return response.json()

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("query")
    parser.add_argument("--max-results", type=int, default=5)
    args = parser.parse_args()
    
    client = MyAwesomeClient()
    result = client.search(args.query, max_results=args.max_results)
    print(result)

Step 4: Add References and Examples

Create helpful documentation in references/:

# Example Python patterns
cat > references/python-examples.md << 'EOF'
# Python Integration Examples

## Async Searches
```python
import asyncio
from client import MyAwesomeClient

async def batch_search(queries):
    client = MyAwesomeClient()
    tasks = [client.search(q) for q in queries]
    return await asyncio.gather(*tasks)

# Run batch
results = asyncio.run(batch_search([...]))

EOF


#### Step 5: Package and Test the Skill

Use the skill-creator packaging tool:

```bash
python /path/to/skill-creator/package_skill.py \
  --skill-dir ~/.openclaw/workspace/skills/my-awesome-skill

This:

Validates SKILL.md format
Checks file structure
Creates a .skill file (metadata)
Prepares for distribution

Step 6: Test in OpenClaw

Your skill is now ready to use:

# CLI
python ~/.openclaw/workspace/skills/my-awesome-skill/scripts/client.py "test"

# In Python agents
from my_awesome_skill.scripts.client import MyAwesomeClient
client = MyAwesomeClient()
result = client.search("query")

Distributing Your Skill

Once tested, you can share your skill:

Option A: Local Distribution

# Copy your skill directory
cp -r ~/.openclaw/workspace/skills/my-awesome-skill /path/to/share/

Option B: GitHub + ClawHub

# Push to GitHub
git add skills/my-awesome-skill/
git commit -m "Add my-awesome-skill"
git push

# Register on ClawHub (clawhub.com)
clawhub publish my-awesome-skill

Users can then install:

clawhub install my-awesome-skill

Real Example: Customizing tavily-search

Let’s say you want to add auto-save results to a file:

1. Edit the Python script:

nano ~/.openclaw/workspace/skills/tavily-search/scripts/tavily_client.py

Add this to TavilySearchClient:

def search_and_save(self, query, output_file=None, **kwargs):
    """Search and optionally save results"""
    result = self.search(query, **kwargs)
    
    if output_file:
        import json
        with open(output_file, 'w') as f:
            json.dump(result, f, indent=2)
        print(f"Saved to {output_file}")
    
    return result

2. Test it:

python scripts/tavily_client.py "python async" \
  --output results.json

3. Update SKILL.md with the new feature:

## Saving Results

```bash
python scripts/tavily_client.py "query" --output results.json


That's it. Your customization is live.

## Performance Tips

1. **Choose appropriate depth:**
   - Use `basic` for 90% of queries (faster, still great answers)
   - Use `advanced` only when you need comprehensive research

2. **Specific queries = better answers**
   - ❌ "machine learning"
   - ✅ "how to use transformers for NLP tasks"

3. **Use topic filtering:**
   - `topic="news"` when searching current events
   - `topic="general"` for technical/historical queries

4. **Batch requests efficiently:**
   - Multiple searches → use Python client with async
   - Single urgent search → use quick mode

5. **Monitor your credit usage:**
   - Check `app.tavily.com` dashboard
   - Track searches in logs to stay under 1,000/month

## Comparison with Other Search Options

| Tool | Speed | AI Answer | API Free Tier | Best For |
|------|-------|-----------|-----------|----------|
| **Tavily** | 180-500ms | ✅ Yes | 1,000 credits/mo | Research, AI agents |
| **Brave Search** | 200-300ms | ❌ No | Limited trial | General web search |
| **Google Search API** | 200ms | ❌ No | Paid only | Production scale |
| **Perplexity API** | 500ms | ✅ Yes | Limited trial | General knowledge |

## Common Questions

**Q: Can I use Tavily locally without the API?**
No — Tavily requires an API key. The endpoint is cloud-hosted. It's designed as a cloud service for rich AI synthesis, not a local tool.

**Q: What happens if I exceed 1,000 credits/month?**
Nothing scary. Your requests will be denied with a "quota exceeded" error. You can upgrade to pay-as-you-go anytime.

**Q: How fast is the API?**
Median response time (p50) is **180ms for answers**. 95th percentile (p95) is around 500ms. Plan for 1-2 second total latency including network overhead.

**Q: Does Tavily cache results?**
Tavily has intelligent caching, so repeated queries for the same thing are faster. But each unique query uses 1 credit.

**Q: Can I use Tavily for commercial projects on the free tier?**
Technically yes — but the 1,000 credit/month limit might not be enough. Consider moving to pay-as-you-go ($0.008/credit) for production.

## Resources

- **Official:** [tavily.com](https://tavily.com)
- **API Platform:** [app.tavily.com](https://app.tavily.com)
- **Pricing:** [tavily.com/pricing](https://www.tavily.com/pricing)
- **OpenClaw Skill:** Included in your workspace (`skills/tavily-search/`)

## Next Steps

### Quick Start (5 minutes)
1. **Sign up** for free at [app.tavily.com](https://app.tavily.com) (no credit card)
2. **Copy your API key** from `app.tavily.com/api`
3. **Store it:** Add `TAVILY_API_KEY="tvly_..."` to `~/.openclaw/workspace/.env`
4. **Test it:** 
   ```bash
   source ~/.openclaw/workspace/.env
   python ~/.openclaw/workspace/skills/tavily-search/scripts/tavily_client.py "python async await"

See the answer — Check the AI-synthesized result

Integration (15 minutes)

Try in an agent: Use the Python client in your OpenClaw agent
Customize if needed: Edit scripts/tavily_client.py for your workflow
Set rate limits: Keep under 1,000 credits/month (33/day)

Advanced (1 hour)

Create your own skill using skill-creator:

python /path/to/skill-creator/init_skill.py --name my-search-skill

Publish to ClawHub (optional):
```
clawhub publish my-search-skill
```

Learn More

Official: tavily.com
API Docs: app.tavily.com
OpenClaw Skills: Check /skills/ in your workspace
Skill-Creator Guide: Read the skill-creator framework docs
Community: Discuss skills on Discord

Want to combine Tavily with other tools? Check out our next post on multi-source research workflows.

What will you build with Tavily? Share your use cases in the comments below. Research assistant? News monitor? Technology decision-maker?