Web Search Skill

Accepts a natural language query, calls the Tavily AI search API, and returns the top matching URLs. Your agent receives those URLs and decides what to do with them, fetch each one, display them, pass them to another skill, etc.

Setup

1. Install the dependency:

pip install tavily-python

2. Set your Tavily API key (free tier: 1,000 searches/month, sign up at https://tavily.com, no credit card required):

# macOS / Linux
export TAVILY_API_KEY="tvly-your-key-here"

# Windows (Command Prompt)
set TAVILY_API_KEY=tvly-your-key-here

# Windows (PowerShell)
$env:TAVILY_API_KEY = "tvly-your-key-here"

3. Optional, cap the number of results (default: 20):

export SYNTHADOC_WEB_SEARCH_MAX_RESULTS=10

Standalone usage

import asyncio
from synthadoc.skills.web_search.scripts.main import WebSearchSkill

skill = WebSearchSkill()

async def main():
    result = await skill.extract("search for: transformer architecture papers")
    urls = result.metadata["child_sources"]   # list[str], top matching URLs
    query = result.metadata["query"]          # "transformer architecture papers"
    print(f"Found {len(urls)} URLs for '{query}':")
    for url in urls:
        print(" ", url)

asyncio.run(main())

result.text is always empty, the skill is a discovery step that returns URLs, not page content. Pass the URLs to the url or youtube skill (or your own HTTP client) to fetch content.

Intent prefixes

The skill strips a leading intent phrase before sending the query to Tavily:

Input	Query sent to Tavily
search for: RAG evaluation	RAG evaluation
find on the web: LLM benchmarks	LLM benchmarks
look up quantum computing	quantum computing
youtube: Karpathy transformers	Karpathy transformers (YouTube only)
搜索: 深度学习架构	深度学习架构