Metadata-Version: 2.4
Name: tavily-agent-toolkit
Version: 0.1.0
Summary: A collection of tools and agents for building AI applications with Tavily
Author-email: Tavily <support@tavily.com>
License: MIT
Project-URL: Homepage, https://github.com/tavily-ai/tavily-cookbook
Project-URL: Documentation, https://docs.tavily.com
Project-URL: Repository, https://github.com/tavily-ai/tavily-cookbook
Keywords: tavily,ai,agents,tools,search,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tavily-python>=0.7.17
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langchain-openai>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"

# Tavily Agent Toolkit

[![PyPI version](https://img.shields.io/pypi/v/tavily-agent-toolkit.svg)](https://pypi.org/project/tavily-agent-toolkit/)

Build production-grade research agents with patterns we've battle-tested across customer deployments and our deep research endpoint.

https://github.com/user-attachments/assets/0b636d61-441b-407a-b2ab-b700dd2d0d0b

▶️ [Here's the link](https://screen.studio/share/lj4IQxMu)

## What This Library Provides

**Tools** — Optimized configurations of Tavily API calls for common research patterns. We handle the context engineering (formatting, deduplication, token management, summarization) so your agent gets clean, relevant data.

**Bring Your Own Model** — Every tool that needs an LLM accepts a `ModelConfig`. We support 20+ providers via [LangChain](https://reference.langchain.com/python/langchain/models/#langchain.chat_models.init_chat_model) with automatic fallback chains. You control the model, we bring our prompts and context engineering strategies.

**Agents** — Pre-built research strategies that combine internal knowledge with web research. Two modes: fast or deep multi-agent research.

## Project Structure

```
agent-toolkit/
├── tools/           # Research primitives
├── agents/          # Pre-built research agents
├── utilities/       # Context engineering utilities
├── models.py        # Type definitions
├── tests/           # Test suite
├── evals/           # Evaluation code and examples for your research agents (coming soon...)
└── use-cases/       # Real-world implementation examples
```

## Tools

Research primitives that combine Tavily endpoints with context engineering. Each tool handles a specific retrieval pattern so your agent can focus on reasoning while we handle the complexity of getting clean, relevant data.

| Tool | Use Case |
|------|----------|
| `search_and_answer` | Answer questions with web research + LLM synthesis |
| `search_dedup` | Run multiple queries in parallel, deduplicate results |
| `crawl_and_summarize` | Extract and summarize entire websites |
| `extract_and_summarize` | Get focused summaries from specific URLs |
| `social_media_search` | Search Reddit, X, LinkedIn, TikTok, etc. |

# Example: Answer a question with comprehensive web research
```bash
pip install tavily-agent-toolkit
```

```python

from tavily_agent_toolkit import social_media_search, ModelConfig, ModelObject

result = social_media_search(
    query="Who is Leo Messi?",
    api_key="tvly-xxx",
)
print(result["result"])
```

> 📖 See [`tools/README.md`](tools/README.md) for detailed documentation, parameters, and examples.

## Agents

### `hybrid_research`

**Use case:** Combine your internal knowledge base with real-time web research.

You provide a RAG function that queries your internal data. The agent identifies gaps and fills them with web research.

**Fast mode:**
1. Query your internal RAG
2. Generate subqueries based on what's missing
3. Parallel web search with deduplication
4. Synthesize everything into a report

**Multi-agent mode:**
1. Query your internal RAG
2. LLM identifies knowledge gaps
3. Tavily's deep research endpoint fills those gaps
4. Synthesize into a comprehensive report

```python
from tavily_agent_toolkit import hybrid_research, ModelConfig, ModelObject

result = await hybrid_research(
    api_key="tvly-xxx",
    query="What is our competitor's pricing strategy?",
    model_config=ModelConfig(model=ModelObject(model="groq:openai/gpt-oss-120b")),
    internal_rag_function=my_rag_function,  # Your RAG
    mode="fast",  # or "multi_agent" for deep research
    output_schema=CompetitorAnalysis,  # Optional structured output
)
```

> 📖 See [`agents/README.MD`](agents/README.MD) for full documentation.

## Utilities

Helper functions that power the tools and agents. A few are reusable on their own: `handle_research_stream`, `clean_raw_content`, `format_web_results`, and `ainvoke_with_fallback` for model cascades.

> 📖 See [`utilities/README.md`](utilities/README.md) for details.

## Use Cases

Production-ready agent implementations demonstrating practical applications. Each example combines multiple Tavily tools with LLM agents to solve real-world problems.

| Use Case | Description |
|----------|-------------|
| Conversational Chatbot | Routes between quick search and deep research based on query complexity |
| Company Intelligence Agent | Crawls websites and searches the web for comprehensive company research |
| Social Media Research Agent | Searches across TikTok, Reddit, X, LinkedIn, and more |

Available in both Anthropic SDK and LangGraph implementations, plus Jupyter notebooks for quick experimentation.

> 📖 See [`use-cases/readme.md`](use-cases/readme.md) for full documentation and examples.

## Installation

> See [CHANGELOG.md](CHANGELOG.md) for release notes.

### Install from PyPI

```bash
pip install tavily-agent-toolkit
```

### Version Pinning

```bash
# Install specific version
pip install tavily-agent-toolkit==0.1.0

# Upgrade to latest
pip install --upgrade tavily-agent-toolkit
```

**In requirements.txt:**

```text
tavily-agent-toolkit>=0.1.0
```

**In pyproject.toml:**

```toml
dependencies = [
    "tavily-agent-toolkit>=0.1.0",
]
```

### Usage

```python
from tavily_agent_toolkit import search_and_answer, crawl_and_summarize, hybrid_research
```

**What's included:**

| Category | Exports |
|----------|---------|
| **Tools** | `search_and_answer`, `search_and_format`, `search_dedup`, `crawl_and_summarize`, `extract_and_summarize`, `social_media_search` |
| **Agents** | `hybrid_research` |
| **Utilities** | `handle_research_stream`, `format_web_results`, `clean_raw_content`, `ainvoke_with_fallback`, and more |
| **Models** | `ModelConfig`, `ModelObject`, `OutputSchema`, and various TypedDicts |

---

### Alternative: Copy the Code

For heavy customization, clone the repo and copy `agent-toolkit/` into your project.

---

### LLM Providers

For LLM features, install your preferred provider:

```bash
pip install langchain-openai       # OpenAI
pip install langchain-anthropic    # Anthropic  
pip install langchain-google-genai # Google
pip install langchain-groq         # Groq
# See models.py for all 20+ supported providers
```

## Model Configuration

All tools accept a `ModelConfig` for LLM operations. Use the `"provider:model"` format:

```python
from models import ModelConfig, ModelObject

config = ModelConfig(
    model=ModelObject(model="openai:gpt-5.2"),
    fallback_models=[  # Optional fallback chain
        ModelObject(model="anthropic:claude-sonnet-4-20250514"),
        ModelObject(model="groq:llama-3.3-70b-versatile"),
    ],
    temperature=0.7,
)
```

**20+ providers supported** via LangChain's [`init_chat_model`](https://reference.langchain.com/python/langchain/models/#langchain.chat_models.init_chat_model): OpenAI, Anthropic, Google, Groq, Mistral, Cohere, Together, Fireworks, AWS Bedrock, Azure, and more.

## Tests

The `tests/` directory contains integration tests for all tools and agents. These tests are a great way to see what the tools look like when they run and understand expected inputs/outputs. With AI coding assistants like Claude Code and Cursor getting better, test-driven development is more accessible and fast than ever—use these as a starting point.

```bash
# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_search_and_answer.py
```

## License

See [LICENSE](../LICENSE) for details.
