langchain-tavily

langchain-tavily is Tavily’s official LangChain integration package, packaging the Tavily web-intelligence API as a set of LangChain BaseTool implementations: TavilySearch, TavilyExtract, TavilyCrawl, TavilyMap, and TavilyResearch/TavilyGetResearch. Each tool wraps a corresponding Tavily REST endpoint behind a Pydantic input schema whose field descriptions are written specifically to steer an LLM’s tool-calling decisions (when to set include_domains, how to pick search_depth or topic, and so on), so agents built with LangChain or LangGraph can call real-time web search, page extraction, site crawling, sitemap discovery, and multi-step research without hand-writing HTTP glue.

Under the hood, each tool defers to a matching *APIWrapper class in _utilities.py that resolves the TAVILY_API_KEY from the environment (or constructor arg) and issues sync (requests) or async (aiohttp) calls to api.tavily.com. The package ships fully typed (py.typed, mypy strict mode) and is tested against LangChain’s own langchain-tests conformance suite, so behavior stays aligned with the wider LangChain tool-calling contract as that ecosystem evolves.

It’s a maintained, first-party integration (not a community wrapper) published directly by Tavily, and is the tool most LangChain/LangGraph agent tutorials reach for when they need the agent to search the live web rather than rely on training-data knowledge.

What You Get

• TavilySearch — real-time web search with tunable depth (basic/advanced/fast/ultra-fast), topic filters (general/news/finance), date-range and domain include/exclude filters, and optional AI-generated answer summaries
• TavilyExtract — pulls cleaned page content (markdown or plain text) from a list of URLs, with optional image extraction
• TavilyCrawl — crawls a site from a base URL with configurable depth/breadth, path and domain include/exclude regex filters, and category filters (docs, pricing, careers, etc.)
• TavilyMap — discovers a site’s URL structure without fetching full page content, useful for scoping a crawl first
• TavilyResearch / TavilyGetResearch — kicks off and retrieves multi-step research reports with selectable model depth (mini/pro/auto), streaming, and structured JSON-schema output
• Fully typed public API (py.typed, mypy disallow_untyped_defs) with sync and async (_run/_arun) implementations for every tool

Common Use Cases

• Giving a LangChain or LangGraph agent real-time web search so answers aren’t limited to the model’s training cutoff
• Building research agents that crawl a competitor’s site or docs and extract structured, cited findings
• Restricting an agent’s search to (or excluding) specific domains, e.g. only official documentation or news sources
• Feeding an agent a site’s URL map before deciding which pages are worth a deeper crawl or extract
• Producing citation-backed research reports on a topic with a single tool call instead of chaining search+extract manually

Under The Hood

Architecture The package follows a flat, single-layer integration pattern rather than a layered architecture: each Tavily REST endpoint (search, extract, crawl, map, research) gets its own file pairing a Pydantic input-schema class with a BaseTool subclass in langchain_tavily/tavily_*.py, and each tool class delegates the actual HTTP call to a matching *APIWrapper class defined in _utilities.py, which owns environment/credential resolution (via a pydantic model_validator) and the sync/async request logic. __init__.py re-exports the five public tool classes as the package’s entire surface area. Because there’s no shared orchestration layer between tools, the wrapper classes in _utilities.py are the single point of coupling to Tavily’s API contract — a REST change there is isolated to one file per endpoint.

Tech Stack Python 3.10+ built with Poetry (poetry-core), depending on exact-pinned langchain-core==1.4.6 and langchain==1.3.9 alongside aiohttp (async HTTP) and requests (sync HTTP) for the underlying Tavily API calls. Dev tooling is comprehensive: ruff for lint/format, mypy in strict mode, codespell for spell-checking, and pytest with pytest-asyncio, pytest-socket (blocks real network calls in unit tests), and pytest-watcher. It has no database or web-framework dependency — it’s a headless SDK consumed by other agent code.

Code Quality Unit tests exist for every tool (tests/unit_tests/test_tavily_*.py) built on LangChain’s own ToolsUnitTests conformance base class from the langchain-tests package, giving standardized coverage of each tool’s schema, serialization, and invocation contract rather than ad hoc assertions; integration tests mirror the same file layout under tests/integration_tests/, gated by pytest-socket so unit runs stay network-free. Errors are surfaced through LangChain’s ToolException type rather than swallowed. The public API is fully typed (py.typed marker, mypy disallow_untyped_defs=True), and naming is consistent throughout (Tavily<Feature> for tools, Tavily<Feature>APIWrapper for the matching HTTP wrapper).

API Design The Pydantic input schemas are unusually thorough as agent-facing documentation: every field’s description is written as explicit guidance for an LLM deciding whether and how to set it (e.g. exactly when to populate include_domains vs exclude_domains, when to pick topic="finance" vs "news"), which is a deliberate design choice for tool-calling reliability rather than generic docstrings. Getting started requires only pip install langchain-tavily, a TAVILY_API_KEY, and zero required constructor arguments beyond the key. The five tools share a single consistent naming convention, making them easy to discover and combine, though deeper reference docs live externally at docs.tavily.com rather than in a dedicated docs site for this package.