> ## 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>TypeScript</strong> integration. For the Python version of
  this guide, see the{" "}
  <a href="/integrations/langchain">Python 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

### Integration details

| Component           | Source                                    |       Package      |
| :------------------ | :---------------------------------------- | :----------------: |
| `ValyuSearchTool`   | Proprietary + public web content (search) | `@valyu/langchain` |
| `ValyuContentsTool` | Web pages (content extraction)            | `@valyu/langchain` |

## Installation

Install the official LangChain Valyu package and the Valyu SDK:

<CodeGroup>
  ```bash npm theme={null} theme={null}
  npm install @valyu/langchain valyu-js @langchain/core
  ```

  ```bash yarn theme={null} theme={null}
  yarn add @valyu/langchain valyu-js @langchain/core
  ```

  ```bash pnpm theme={null} theme={null}
  pnpm add @valyu/langchain valyu-js @langchain/core
  ```
</CodeGroup>

Configure credentials by setting the following environment variable:

```typescript theme={null} theme={null}
process.env.VALYU_API_KEY = "your-valyu-api-key-here";
```

Or set it programmatically:

```typescript theme={null} theme={null}
import * as dotenv from "dotenv";
dotenv.config();
```

For agent examples, you'll also need:

```typescript theme={null} theme={null}
process.env.ANTHROPIC_API_KEY = "your-anthropic-api-key";
process.env.OPENAI_API_KEY = "your-openai-api-key";
```

<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

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const tool = new ValyuSearchTool({
  client: valyuClient,
});

const searchResults = await tool.invoke({
  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,
});

console.log("Search Results:", JSON.parse(searchResults));
```

### Using ValyuContentsTool for Content Extraction

Extract clean, structured content from specific URLs:

```typescript theme={null} theme={null}
import { ValyuContentsTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const contentsTool = new ValyuContentsTool({
  client: valyuClient,
});

const urls = [
  "https://arxiv.org/abs/2301.00001",
  "https://example.com/article",
];

const extractedContent = await contentsTool.invoke({ urls });
const results = JSON.parse(extractedContent);

console.log("Extracted Content:", results.results);

for (const result of results.results || []) {
  console.log(`URL: ${result.url}`);
  console.log(`Title: ${result.title}`);
  console.log(`Content: ${result.content?.substring(0, 200)}...`);
  console.log(`Status: ${result.status}`);
  console.log("---");
}
```

### 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 npm theme={null} theme={null}
npm install @langchain/anthropic @langchain/langgraph
```

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";
import { ChatAnthropic } from "@langchain/anthropic";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { HumanMessage } from "@langchain/core/messages";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const llm = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const valyuSearchTool = new ValyuSearchTool({
  client: valyuClient,
});

const agent = createReactAgent({ llm, tools: [valyuSearchTool] });

const userInput =
  "What are the key factors driving recent stock market volatility, and how do macroeconomic indicators influence equity prices across different sectors?";

const stream = await agent.stream({
  messages: [new HumanMessage(userInput)],
});

for await (const step of stream) {
  console.log(step.messages[step.messages.length - 1].content);
}
```

## Advanced Configuration

### Search Parameters

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

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const tool = new ValyuSearchTool({
  client: valyuClient,
});

const results = await tool.invoke({
  query: "quantum computing breakthroughs 2024",
  search_type: "all", // "all", "web", or "proprietary" - Note: use "all" when using included_sources with URLs
  max_num_results: 10, // 1-20 results for standard API keys, up to 100 with a special API key
  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:

```typescript theme={null} theme={null}
const academicResults = await tool.invoke({
  query: "machine learning research 2024",
  search_type: "all", // Use "all" when including specific source URLs/domains
  included_sources: ["arxiv.org", "pubmed.ncbi.nlm.nih.gov", "ieee.org"],
  max_num_results: 8,
});

const filteredResults = await tool.invoke({
  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:

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";
import { ChatAnthropic } from "@langchain/anthropic";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { HumanMessage } from "@langchain/core/messages";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const researchLLM = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  temperature: 0.1,
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const researchTool = new ValyuSearchTool({
  client: valyuClient,
});

const researchAgent = createReactAgent({
  llm: researchLLM,
  tools: [researchTool],
});

const analysisLLM = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  temperature: 0.3,
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const analysisAgent = createReactAgent({
  llm: analysisLLM,
  tools: [researchTool],
});

const researchQuery =
  "Find recent papers on transformer architecture improvements";
const analysisQuery = "Analyze market trends in AI chip demand";

const researchStream = await researchAgent.stream({
  messages: [new HumanMessage(researchQuery)],
});

for await (const step of researchStream) {
  console.log(step.messages[step.messages.length - 1].content);
}

const analysisStream = await analysisAgent.stream({
  messages: [new HumanMessage(analysisQuery)],
});

for await (const step of analysisStream) {
  console.log(step.messages[step.messages.length - 1].content);
}
```

## Example Applications

### Financial Research Assistant

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";
import { ChatAnthropic } from "@langchain/anthropic";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const financialLLM = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const valyuTool = new ValyuSearchTool({
  client: valyuClient,
});

const financialAgent = createReactAgent({
  llm: financialLLM,
  tools: [valyuTool],
});

const query =
  "What are the latest developments in cryptocurrency regulation and their impact on institutional adoption?";

const systemContext =
  new SystemMessage(`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.`);

const stream = await financialAgent.stream({
  messages: [systemContext, new HumanMessage(query)],
});

for await (const step of stream) {
  console.log(step.messages[step.messages.length - 1].content);
}
```

### Academic Research Agent

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const academicTool = new ValyuSearchTool({
  client: valyuClient,
});

const academicResults = await academicTool.invoke({
  query: "CRISPR gene editing safety protocols",
  search_type: "proprietary", // Focus on academic datasets
  max_num_results: 8,
  relevance_threshold: 0.6,
});

const results = JSON.parse(academicResults);
console.log("Academic Sources:", results.results);

for (const result of results.results || []) {
  console.log(`Title: ${result.title}`);
  console.log(`Source: ${result.source}`);
  console.log(`Relevance: ${result.relevance_score}`);
  console.log("---");
}
```

## Best Practices

### 1. **Cost Optimization**

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const tool = new ValyuSearchTool({
  client: valyuClient,
});

const quickSearch = await tool.invoke({
  query: "current bitcoin price",
  max_price: 30.0,
  max_num_results: 3,
});

const detailedSearch = await tool.invoke({
  query: "comprehensive analysis of renewable energy trends",
  max_price: 50.0,
  max_num_results: 15,
  search_type: "all",
});
```

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

```typescript theme={null} theme={null}
const webResults = await tool.invoke({
  query: "latest AI policy developments",
  search_type: "web",
  max_num_results: 5,
});

const academicResults = await tool.invoke({
  query: "machine learning interpretability methods",
  search_type: "proprietary",
  max_num_results: 8,
});

const allResults = await tool.invoke({
  query: "climate change economic impact",
  search_type: "all",
  max_num_results: 10,
});
```

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

```typescript theme={null} theme={null}
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

async function robustSearch(
  query: string,
  fallbackQuery?: string
): Promise<string> {
  const tool = new ValyuSearchTool({
    client: valyuClient,
  });

  try {
    const results = await tool.invoke({
      query: query,
      max_price: 30.0,
      max_num_results: 5,
    });
    return results;
  } catch (error) {
    console.error(`Primary search failed: ${error}`);

    if (fallbackQuery) {
      try {
        const results = await tool.invoke({
          query: fallbackQuery,
          max_price: 30.0,
          max_num_results: 3,
          search_type: "web",
        });
        return results;
      } catch (error2) {
        console.error(`Fallback search also failed: ${error2}`);
        return JSON.stringify({ error: "Search unavailable" });
      }
    }

    return JSON.stringify({ error: "Search failed" });
  }
}

const results = await robustSearch(
  "complex quantum entanglement applications",
  "quantum entanglement basics"
);
```

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

```typescript theme={null} theme={null}
import { SystemMessage, HumanMessage } from "@langchain/core/messages";
import { ValyuSearchTool, ValyuAdapter } from "@valyu/langchain";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatAnthropic } from "@langchain/anthropic";

const valyuClient = new ValyuAdapter(process.env.VALYU_API_KEY!);

const systemMessage =
  new SystemMessage(`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="all" for comprehensive research
- Set higher relevance_threshold (0.6+) for precise results
- 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`);

const llm = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const valyuTool = new ValyuSearchTool({
  client: valyuClient,
});

const agent = createReactAgent({ llm, tools: [valyuTool] });

const stream = await agent.stream({
  messages: [systemMessage, new HumanMessage("Your query here")],
});

for await (const step of stream) {
  console.log(step.messages[step.messages.length - 1].content);
}
```

<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 string
* **`search_type`**: `"all"`, `"web"`, or `"proprietary"` (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: 10)
* **`relevance_threshold`**: 0.0-1.0 relevance score threshold (default: 0.5)
* **`max_price`**: Maximum cost in dollars (default: 50.0)
* **`is_tool_call`**: Optimize for LLM consumption (default: true)
* **`start_date`**: Start date for time filtering in YYYY-MM-DD format (optional)
* **`end_date`**: End date for time filtering in YYYY-MM-DD format (optional)
* **`included_sources`**: Array of URLs/domains/datasets to include (optional)
* **`excluded_sources`**: Array of URLs/domains/datasets to exclude (optional)
* **`response_length`**: Content length - number (character count), "short", "medium", "large", or "max" (optional)
* **`country_code`**: 2-letter ISO country code for geo-bias, e.g., "US", "GB" (optional)
* **`fast_mode`**: Enable for faster but shorter results (default: false)

**Note:** The tool returns a JSON string. Use `JSON.parse()` to convert it to an object. The response structure includes a `results` array with search results.

### ValyuContentsTool Parameters

**Invoke Parameters:**

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

**Constructor Options (optional):**

* **`summary`**: Generate summaries for extracted content (boolean, string, or object)
* **`extract_effort`**: Extraction effort level - `"normal"`, `"high"`, or `"auto"` (default: `"normal"`)
* **`response_length`**: Content length - number (character count), `"short"`, `"medium"`, `"large"`, or `"max"` (default: `"short"`)

## Additional Resources

<CardGroup>
  <Card title="LangChain Valyu Tool" icon="link" href="https://python.langchain.com/docs/integrations/tools/valyu_search/">
    Official LangChain Python 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://js.langchain.com/docs/langgraph">
    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>