Tavily Python SDK
Integrate Tavily's smart search, extraction, crawling, mapping, and research capabilities directly into your Python applications.
- Source repo
- tavily-ai/tavily-python
- Stars
- ★ 1.4k
- Last updated
- 12d ago
- License
- MIT
- Primary language
- Python
- FA score
- 46/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who need to integrate real-time web search into AI applications, using search for fresh information.
- Not a fit if
- Teams that need fully offline use; every feature calls Tavily's cloud API
- Users needing crawl, map, or research; those endpoints require a key and crawl is invite-only
- High-concurrency production; keyless mode is rate-limited and the free tier is 1,000 credits/month
- Source review
- 46/100 · Major gaps 3 safety controls not found
What does this agent do, and when should you use it?
The Tavily Python SDK is an official library for interacting with the Tavily API, offering the full range of search, extract, crawl, map, and research functionalities. It features a keyless mode for quick trials of search and extract, while full capabilities require an API key. The SDK provides both synchronous and asynchronous clients, supports custom session injection, and enables request tracking. Aimed at developers, it simplifies adding web search and content extraction to applications, particularly for RAG and AI systems needing real-time web data.
The SDK exposes core capabilities through TavilyClient and AsyncTavilyClient: search performs web searches and returns results; get_search_context generates context strings suitable for RAG; qna_search returns direct answers. extract retrieves raw content and images from multiple URLs; crawl traverses a website from a start URL; map discovers site structure; research creates research reports and supports streaming. It also supports injecting a custom requests.Session or httpx.AsyncClient for API gateways, and request tracking via identifiers like project_id and session_id. All methods return standard dictionaries or streaming responses.
- Developers who need to integrate real-time web search into AI applications, using search for fresh information.
- Teams building RAG applications, using get_search_context to generate fact-based context for better generation accuracy.
- Users who need to extract structured content from multiple web pages, using extract to batch-fetch raw text and images.
- SEO or content analysts needing to analyze site structure, using map to visualize site hierarchy.
- Researchers automating report generation, using research to create reports asynchronously and retrieve results.
- Developers in enterprise environments proxying requests through an API gateway, using custom session injection for centralized auth.
How do you install or deploy this agent?
Install via pip: pip install tavily-python. Requires a Python 3.x environment. No API key is needed for trials, but full features require signing up at tavily.com and obtaining an API key.
How do you use this agent?
First, import and instantiate the client: from tavily import TavilyClient; client = TavilyClient(api_key="tvly-YOUR_API_KEY"). Then call methods, e.g., response = client.search("Who is Leo Messi?"). In keyless mode, omit the api_key. For async, use from tavily import AsyncTavilyClient and await calls.
What are this agent's strengths and limitations?
- Offers a keyless trial mode, lowering the entry barrier for quick evaluation.
- Covers five major functionalities—search, extract, crawl, map, and research—addressing diverse web data needs.
- Supports both synchronous and asynchronous clients, fitting various application scenarios.
- Custom session injection enables centralized management via API gateways in enterprise environments.
- Core features depend on Tavily's proprietary API, posing a vendor lock-in risk.
- Crawl, map, and research features require an API key, and crawl is currently invite-only.
- Keyless mode has rate limits, unsuitable for high-concurrency production use.
- Free tier allows 1,000 credits per month; additional usage incurs costs, so long-term expenses need evaluation.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Tavily Python SDK This agent | 46 · Major gaps | Library / SDKFreemium | ★ 1.4k | 12d ago | Python | — |
| wigolo | 54 · Major gaps | CLIFree + model costs | ★ 5.5k | 22d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Youtu-Agent | 27 · Major gaps | CLIFree + model costs | ★ 4.6k | 7mo ago | Python | OpenAI API |
| Atomic Agents | 64 · Some gaps | Library / SDKFree + model costs | ★ 6.3k | today | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: SDK supports custom session/client injection, allowing user control over auth and proxies, but defaults to API key, lacking least privilege; no user confirmation mechanism; data flow transparency is good, README clearly states request headers, session tracking, and human_id hashing; sensitive data handling: API key passed as parameter, but storage or logging not addressed; dependency security not mentioned, requirements.txt lists only package names without versions; external effects: SDK makes network requests, but rate limiting or abuse protection not documented; rollback mechanism not mentioned; source attribution: MIT license and copyright notice present, but publisher unverified. Deductions: lack of least privilege design, user confirmation, dependency security, rollback, incomplete sensitive data handling.
Evidence: README and code examples are consistent, API method naming is clear; dependency availability: requirements.txt lists only package names without versions, risking dependency drift; failure messages: README mentions TavilyKeylessLimitError exception with structured fields, but other error handling not shown. Deductions: dependency versions not pinned, error handling coverage incomplete.
Evidence: README targets developers, provides multiple use cases (search, extract, crawl, map, research) with code examples; capability boundaries clear, keyless mode limited to search and extract; trigger precision: method parameters documented in detail, but full API reference not provided; environment fit: supports sync and async clients, custom session injection. Deductions: trigger precision limited by lack of full API reference.
Evidence: README well-structured, includes installation, usage, documentation links; install notes simple; naming stable, API methods intuitive; examples abundant, covering main features; known limitations: only keyless mode limitation mentioned, others not; license MIT, copyright notice present; versioning changelog not provided; maintenance responsibility: support email and community links, but publisher unverified. Deductions: missing versioning changelog, incomplete known limitations.
Evidence: Output usability: returns structured JSON responses, easy for programmatic use; marginal value: provides advanced features like search, extract, crawl, map, research, simplifying API interaction; cost benefit: free tier 1000 credits/month, but detailed pricing not provided. Deductions: cost information incomplete.
Evidence: README feature descriptions align with code examples, but no independent test results or third-party verification; cross-source corroboration: CI badge present, but test details not provided; fact vs inference separation: README distinguishes feature descriptions and examples, but does not explicitly mark inferences. Deductions: lack of independent verification and test evidence.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; confirm source trustworthiness before use.
- Dependency versions not pinned, posing supply chain risk; consider locking versions.
- API key passed as parameter; be cautious with logging and storage.
- No versioning changelog; exercise caution when upgrading.