LangChain Integration

Overview

Viewing the TypeScript integration. For the Python version of this guide, see the Python LangChain integration.

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:

npm install @valyu/langchain valyu-js @langchain/core

Configure credentials by setting the following environment variable:

process.env.VALYU_API_KEY = "your-valyu-api-key-here";

Or set it programmatically:

import * as dotenv from "dotenv";
dotenv.config();

For agent examples, you’ll also need:

process.env.ANTHROPIC_API_KEY = "your-anthropic-api-key";
process.env.OPENAI_API_KEY = "your-openai-api-key";

Free Credits

Get your API key with $10 credit from the Valyu Platform.

Basic Usage

Using ValyuSearchTool for Deep Search

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:

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:

npm

npm install @langchain/anthropic @langchain/langgraph

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:

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:

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:

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

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

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

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

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

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

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);
}

For complete query writing guidelines and how to use API parameters instead, see the Prompting Guide.

API Reference

For complete parameter documentation, see the Valyu API Reference.

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 (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")

LangChain Integration

Overview

Integration details

Installation

Free Credits

Basic Usage

Using ValyuSearchTool for Deep Search

Using ValyuContentsTool for Content Extraction

Using with LangChain Agents

Advanced Configuration

Search Parameters

Source Filtering

Multi-Agent Workflows

Example Applications

Financial Research Assistant

Academic Research Agent

Best Practices

1. Cost Optimization

2. Search Type Selection

3. Error Handling and Fallbacks

4. Agent System Messages

API Reference

ValyuSearchTool Parameters

ValyuContentsTool Parameters

Additional Resources

LangChain Valyu Tool

API Reference

LangGraph Agents

Get API Key

Documentation Index

​Overview

​Integration details

​Installation

Free Credits

​Basic Usage

​Using ValyuSearchTool for Deep Search

​Using ValyuContentsTool for Content Extraction

​Using with LangChain Agents

​Advanced Configuration

​Search Parameters

​Source Filtering

​Multi-Agent Workflows

​Example Applications

​Financial Research Assistant

​Academic Research Agent

​Best Practices

​1. Cost Optimization

​2. Search Type Selection

​3. Error Handling and Fallbacks

​4. Agent System Messages

​API Reference

​ValyuSearchTool Parameters

​ValyuContentsTool Parameters

​Additional Resources

LangChain Valyu Tool

API Reference

LangGraph Agents

Get API Key

Overview

Integration details

Installation

Basic Usage

Using ValyuSearchTool for Deep Search

Using ValyuContentsTool for Content Extraction

Using with LangChain Agents

Advanced Configuration

Search Parameters

Source Filtering

Multi-Agent Workflows

Example Applications

Financial Research Assistant

Academic Research Agent

Best Practices

1. Cost Optimization

2. Search Type Selection

3. Error Handling and Fallbacks

4. Agent System Messages

API Reference

ValyuSearchTool Parameters

ValyuContentsTool Parameters

Additional Resources