> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain Integration

> Use Valyu as a tool in your LangChain applications and agents

## Overview

<Tip>
  Viewing the <strong>Python</strong> integration. For the TypeScript version of
  this guide, see the{" "}
  <a href="/integrations/langchain-js">TypeScript LangChain integration</a>.
</Tip>

Valyu integrates seamlessly with LangChain as a search tool, allowing you to enhance your AI agents and RAG applications with **real-time web search** and **proprietary data sources**. The integration provides LLM-ready context from multiple sources including web pages, academic journals, financial data, and more.

The package includes two main tools:

* **`ValyuSearchTool`**: Deep search operations with comprehensive parameter control
* **`ValyuContentsTool`**: Extract clean content from specific URLs

## Installation

Install the official LangChain Valyu package:

```bash theme={null}
pip install -U langchain-valyu
```

Configure credentials by setting the following environment variable:

```bash theme={null}
export VALYU_API_KEY="your-valyu-api-key-here"
```

Or set it programmatically:

```python theme={null}
import os
os.environ["VALYU_API_KEY"] = "your-valyu-api-key-here"
```

For agent examples, you'll also need:

```bash theme={null}
export ANTHROPIC_API_KEY="your-anthropic-api-key"  # For Claude examples
export OPENAI_API_KEY="your-openai-api-key"        # For OpenAI examples
```

<Card title="Free Credits" icon="gift" href="https://platform.valyu.ai" horizontal>
  Get your API key with \$10 credit from the Valyu Platform.
</Card>

## Basic Usage

### Using ValyuSearchTool for Deep Search

```python theme={null}
import os
from langchain_valyu import ValyuSearchTool

# Set your API key
os.environ["VALYU_API_KEY"] = "your-api-key-here"

# Initialize the search tool
tool = ValyuSearchTool()

# Perform a search
search_results = tool._run(
    query="What are agentic search-enhanced large reasoning models?",
    search_type="all",  # "all", "web", or "proprietary"
    max_num_results=5,
    relevance_threshold=0.5,
    max_price=30.0
)

print("Search Results:", search_results.results)
```

### Using ValyuContentsTool for Content Extraction

Extract clean, structured content from specific URLs:

```python theme={null}
import os
from langchain_valyu import ValyuContentsTool

# Set your API key
os.environ["VALYU_API_KEY"] = "your-api-key-here"

# Initialize the contents tool
contents_tool = ValyuContentsTool()

# Extract content from URLs
urls = [
    "https://arxiv.org/abs/2301.00001",
    "https://example.com/article",
]

extracted_content = contents_tool._run(urls=urls)
print("Extracted Content:", extracted_content.results)

# Print individual results
for result in extracted_content.results:
    print(f"URL: {result['url']}")
    print(f"Title: {result['title']}")
    print(f"Content: {result['content'][:200]}...")
    print(f"Status: {result['status']}")
    print("---")
```

### Using with LangChain Agents

The most powerful way to use Valyu is within LangChain agents, where the AI can dynamically decide when and how to search:

```bash theme={null}
pip install langchain-anthropic langgraph
```

```python theme={null}
import os
from langchain_valyu import ValyuSearchTool
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage

# Set API keys
os.environ["VALYU_API_KEY"] = "your-valyu-api-key"
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"

# Initialize components
llm = ChatAnthropic(model="claude-sonnet-4-20250514")
valyu_search_tool = ValyuSearchTool()

# Create agent with Valyu search capability
agent = create_react_agent(llm, [valyu_search_tool])

# Use the agent
user_input = "What are the key factors driving recent stock market volatility, and how do macroeconomic indicators influence equity prices across different sectors?"

for step in agent.stream(
    {"messages": [HumanMessage(content=user_input)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()
```

## Advanced Configuration

### Search Parameters

The ValyuSearchTool supports comprehensive search parameters for fine-tuned control:

```python theme={null}
from langchain_valyu import ValyuSearchTool

tool = ValyuSearchTool()

# Advanced search with all available parameters
results = tool._run(
    query="quantum computing breakthroughs 2024",
    search_type="proprietary",  # "all", "web", or "proprietary"
    max_num_results=10,  # 1-20 results for standard API keys, up to 100 with a [special API key](http://platform.valyu.ai/user/account/apikeys?req=increase_results)
    relevance_threshold=0.6,  # 0.0-1.0 relevance score
    max_price=30.0,  # Maximum cost in dollars
    is_tool_call=True,  # Optimized for LLM consumption
    start_date="2024-01-01",  # Time filtering (YYYY-MM-DD)
    end_date="2024-12-31",
    included_sources=["valyu/valyu-arxiv", "valyu/valyu-pubmed"],  # Include specific sources
    excluded_sources=["example.com"],  # Exclude sources
    response_length="medium",  # "short", "medium", "large", "max", or int
    country_code="US",  # 2-letter ISO country code
    fast_mode=False,  # Enable for faster but shorter results
)
```

### Source Filtering

Control which sources are included or excluded from your search:

```python theme={null}
# Include only academic sources
academic_results = tool._run(
    query="machine learning research 2024",
    search_type="proprietary",
    included_sources=["arxiv.org", "pubmed.ncbi.nlm.nih.gov", "ieee.org"],
    max_num_results=8
)

# Exclude specific domains
filtered_results = tool._run(
    query="AI policy developments",
    search_type="web",
    excluded_sources=["example.com", "example.org", "example.net"],
    max_num_results=10
)
```

### Multi-Agent Workflows

Use Valyu in complex multi-agent systems:

```python theme={null}
from langchain_valyu import ValyuSearchTool
from langchain_anthropic import ChatAnthropic
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage

# Create specialized research agent
research_llm = ChatAnthropic(model="claude-sonnet-4-20250514", temperature=0.1)
research_tool = ValyuSearchTool()

research_agent = create_react_agent(
    research_llm,
    [research_tool]
)

# Create analysis agent
analysis_llm = ChatOpenAI(model="gpt-5", temperature=0.3)
analysis_agent = create_react_agent(
    analysis_llm,
    [research_tool]
)

# Coordinate agents for complex queries
research_query = "Find recent papers on transformer architecture improvements"
analysis_query = "Analyze market trends in AI chip demand"

# Execute research agent
for step in research_agent.stream(
    {"messages": [HumanMessage(content=research_query)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()

# Execute analysis agent
for step in analysis_agent.stream(
    {"messages": [HumanMessage(content=analysis_query)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()
```

## Example Applications

### Financial Research Assistant

```python theme={null}
from langchain_valyu import ValyuSearchTool
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage, SystemMessage

# Create financial research agent
financial_llm = ChatAnthropic(model="claude-sonnet-4-20250514")
valyu_tool = ValyuSearchTool()

financial_agent = create_react_agent(financial_llm, [valyu_tool])

# Query financial markets with system context
query = "What are the latest developments in cryptocurrency regulation and their impact on institutional adoption?"

system_context = SystemMessage(content="""You are a financial research assistant. Use Valyu to search for:
- Real-time market data and news
- Academic research on financial models
- Economic indicators and analysis

Always cite your sources and provide context about data recency.""")

for step in financial_agent.stream(
    {"messages": [system_context, HumanMessage(content=query)]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()
```

### Academic Research Agent

```python theme={null}
from langchain_valyu import ValyuSearchTool

# Configure for academic research
academic_tool = ValyuSearchTool()

# Search academic sources specifically
academic_results = academic_tool._run(
    query="CRISPR gene editing safety protocols",
    search_type="proprietary",  # Focus on academic datasets
    max_num_results=8,
    relevance_threshold=0.6,
)

print("Academic Sources Found:", len(academic_results.results))
for result in academic_results.results:
    print(f"Title: {result['title']}")
    print(f"Source: {result['source']}")
    print(f"Relevance: {result['relevance_score']}")
    print("---")
```

## Best Practices

### 1. **Cost Optimization**

```python theme={null}
# Set appropriate price limits based on use case
tool = ValyuSearchTool()

# For quick lookups
quick_search = tool._run(
    query="current bitcoin price",
    max_price=30.0,  # Lower cost for simple queries
    max_num_results=3
)

# For comprehensive research
detailed_search = tool._run(
    query="comprehensive analysis of renewable energy trends",
    max_price=50.0,  # Higher budget for complex queries
    max_num_results=15,
    search_type="all"
)
```

### 2. **Search Type Selection**

```python theme={null}
# Web search for current events
web_results = tool._run(
    query="latest AI policy developments",
    search_type="web",
    max_num_results=5
)

# Proprietary search for academic research
academic_results = tool._run(
    query="machine learning interpretability methods",
    search_type="proprietary",
    max_num_results=8
)

# Combined search for comprehensive coverage
all_results = tool._run(
    query="climate change economic impact",
    search_type="all",
    max_num_results=10
)
```

### 3. **Error Handling and Fallbacks**

```python theme={null}
from langchain_valyu import ValyuSearchTool

def robust_search(query: str, fallback_query: str = None):
    tool = ValyuSearchTool()

    try:
        # Primary search
        results = tool._run(
            query=query,
            max_price=30.0,
            max_num_results=5
        )
        return results
    except Exception as e:
        print(f"Primary search failed: {e}")

        if fallback_query:
            try:
                # Fallback with simpler query
                results = tool._run(
                    query=fallback_query,
                    max_price=30.0,
                    max_num_results=3,
                    search_type="web"
                )
                return results
            except Exception as e2:
                print(f"Fallback search also failed: {e2}")
                return "Search unavailable"

        return "Search failed"

# Usage
results = robust_search(
    "complex quantum entanglement applications",
    "quantum entanglement basics"
)
```

### 4. **Agent System Messages**

```python theme={null}
from langchain_core.messages import SystemMessage, HumanMessage

# Optimize agent behavior with good system messages
system_message = SystemMessage(content="""You are an AI research assistant with access to Valyu search.

SEARCH GUIDELINES:
- Use search_type="proprietary" for academic/scientific queries
- Use search_type="web" for current events and general web content
- Use search_type="news" for news articles only
- Use search_type="all" for comprehensive research
- Set higher relevance_threshold (0.6+) for precise results
- Use category parameter to guide search context
- Do not use search operators (e.g., site:, OR, AND, quotes). Use natural keyword queries instead.
- Always cite sources from search results

RESPONSE FORMAT:
- Provide direct answers based on search results
- Include source citations with URLs when available
- Mention publication dates for time-sensitive information
- Indicate if information might be outdated""")

valyu_tool = ValyuSearchTool()
agent = create_react_agent(llm, [valyu_tool])

# Use the agent with system context
for step in agent.stream(
    {"messages": [system_message, HumanMessage(content="Your query here")]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()
```

<Tip>
  For complete query writing guidelines and how to use API parameters instead, see the [Prompting Guide](/search/prompting).
</Tip>

## API Reference

For complete parameter documentation, see the [Valyu API Reference](/api-reference/endpoint/search).

### ValyuSearchTool Parameters

* **`query`** (required): Natural language search query
* **`search_type`**: `"all"`, `"web"`, `"proprietary"`, or `"news"` (default: "all")
* **`max_num_results`**: 1-20 results for standard API keys, up to 100 with a [special API key](http://platform.valyu.ai/user/account/apikeys?req=increase_results) (default: 5)
* **`relevance_threshold`**: 0.0-1.0 relevance score (default: 0.5)
* **`max_price`**: Maximum cost in dollars per thousand retrievals (CPM). Only applies when provided. If not provided, adjusts automatically based on search type and max number of results.
* **`is_tool_call`**: Optimize for LLM consumption (default: true)
* **`start_date`/`end_date`**: Time filtering in YYYY-MM-DD format (optional)
* **`included_sources`**: List of URLs/domains to include (optional)
* **`excluded_sources`**: List of URLs/domains to exclude (optional)
* **`response_length`**: Content length - int, "short", "medium", "large", "max" (optional)
* **`country_code`**: 2-letter ISO country code for geo-bias (optional)
* **`fast_mode`**: Enable for faster but shorter results (default: false)

### ValyuContentsTool Parameters

* **`urls`** (required): List of URLs to extract content from (max 10 per request)

## Additional Resources

<CardGroup>
  <Card title="LangChain Valyu Tool" icon="link" href="https://python.langchain.com/docs/integrations/tools/valyu_search/">
    Official LangChain integration documentation
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/search">
    Complete Valyu API documentation
  </Card>

  <Card title="LangGraph Agents" icon="robot" href="https://docs.langchain.com/oss/python/langgraph/overview">
    Build advanced agent workflows
  </Card>

  <Card title="Get API Key" icon="key" href="https://platform.valyu.ai">
    Sign up for free \$10 credit
  </Card>
</CardGroup>