@librechat/agents 3.1.75 → 3.1.77-dev.1

package/src/tools/search/tool.ts

@@ -14,6 +14,7 @@ import {
 } from './schema';
 import { createSearchAPI, createSourceProcessor } from './search';
 import { createSerperScraper } from './serper-scraper';
+import { createTavilyScraper } from './tavily-scraper';
 import { createFirecrawlScraper } from './firecrawl';
 import { expandHighlights } from './highlights';
 import { formatResultsForLLM } from './format';
@@ -178,11 +179,13 @@ async function executeParallelSearches({
 function createSearchProcessor({
   searchAPI,
   safeSearch,
+  supportsVideos,
   sourceProcessor,
   onGetHighlights,
   logger,
 }: {
   safeSearch: t.SearchToolConfig['safeSearch'];
+  supportsVideos: boolean;
   searchAPI: ReturnType<typeof createSearchAPI>;
   sourceProcessor: ReturnType<typeof createSourceProcessor>;
   onGetHighlights: t.SearchToolConfig['onGetHighlights'];
@@ -218,7 +221,7 @@ function createSearchProcessor({
         country,
         safeSearch,
         images,
-        videos,
+        videos: supportsVideos && videos,
         news,
         logger,
       });
@@ -306,32 +309,12 @@ function createTool({
 }
 
 /**
- * Creates a search tool with a schema that dynamically includes the country field
- * only when the searchProvider is 'serper'.
- *
- * Supports multiple scraper providers:
- * - Firecrawl (default): Full-featured web scraping with multiple formats
- * - Serper: Lightweight scraping using Serper's scrape API
- *
- * @example
- * ```typescript
- * // Using Firecrawl scraper (default)
- * const searchTool = createSearchTool({
- *   searchProvider: 'serper',
- *   scraperProvider: 'firecrawl',
- *   firecrawlApiKey: 'your-firecrawl-key'
- * });
+ * Creates a search tool with configurable search and scraper providers.
  *
- * // Using Serper scraper
- * const searchTool = createSearchTool({
- *   searchProvider: 'serper',
- *   scraperProvider: 'serper',
- *   serperApiKey: 'your-serper-key'
- * });
- * ```
+ * Search providers: Serper (Google results), SearXNG (self-hosted meta-search), Tavily (AI-optimized).
+ * Scraper providers: Firecrawl (default, full-featured), Serper (lightweight), Tavily (batch extraction).
  *
- * @param config - The search tool configuration
- * @returns A DynamicStructuredTool with a schema that depends on the searchProvider
+ * The country schema field is exposed to the LLM for providers that support localized results.
  */
 /** Input params type for search tool */
 interface SearchToolParams {
@@ -351,6 +334,10 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    tavilyApiKey,
+    tavilySearchUrl,
+    tavilyExtractUrl,
+    tavilySearchOptions,
     rerankerType = 'cohere',
     topResults = 5,
     strategies = ['no_extraction'],
@@ -362,6 +349,7 @@ export const createSearchTool = (
     firecrawlVersion,
     firecrawlOptions,
     serperScraperOptions,
+    tavilyScraperOptions,
     scraperTimeout,
     jinaApiKey,
     jinaApiUrl,
@@ -371,6 +359,13 @@ export const createSearchTool = (
   } = config;
 
   const logger = config.logger || createDefaultLogger();
+  const effectiveTavilySearchOptions =
+    searchProvider === 'tavily' && config.safeSearch != null
+      ? {
+        ...tavilySearchOptions,
+        safeSearch: config.safeSearch !== 0,
+      }
+      : tavilySearchOptions;
 
   const schemaProperties: Record<string, unknown> = {
     query: querySchema,
@@ -380,7 +375,7 @@ export const createSearchTool = (
     news: newsSchema,
   };
 
-  if (searchProvider === 'serper') {
+  if (searchProvider === 'serper' || searchProvider === 'tavily') {
     schemaProperties.country = countrySchema;
   }
 
@@ -395,6 +390,9 @@ export const createSearchTool = (
     serperApiKey,
     searxngInstanceUrl,
     searxngApiKey,
+    tavilyApiKey,
+    tavilySearchUrl,
+    tavilySearchOptions: effectiveTavilySearchOptions,
   });
 
   /** Create scraper based on scraperProvider */
@@ -407,6 +405,17 @@ export const createSearchTool = (
       timeout: scraperTimeout ?? serperScraperOptions?.timeout,
       logger,
     });
+  } else if (scraperProvider === 'tavily') {
+    scraperInstance = createTavilyScraper({
+      ...tavilyScraperOptions,
+      apiKey:
+        tavilyScraperOptions?.apiKey ??
+        tavilyApiKey ??
+        process.env.TAVILY_API_KEY,
+      apiUrl: tavilyScraperOptions?.apiUrl ?? tavilyExtractUrl,
+      timeout: scraperTimeout ?? tavilyScraperOptions?.timeout,
+      logger,
+    });
   } else {
     scraperInstance = createFirecrawlScraper({
       ...firecrawlOptions,
@@ -445,6 +454,7 @@ export const createSearchTool = (
   const search = createSearchProcessor({
     searchAPI,
     safeSearch,
+    supportsVideos: searchProvider !== 'tavily',
     sourceProcessor,
     onGetHighlights,
     logger,

package/src/tools/search/types.ts

@@ -3,8 +3,8 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
 
-export type SearchProvider = 'serper' | 'searxng';
-export type ScraperProvider = 'firecrawl' | 'serper';
+export type SearchProvider = 'serper' | 'searxng' | 'tavily';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 
 export interface Highlight {
@@ -62,11 +62,59 @@ export interface Source {
   date?: string;
 }
 
+export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
+export type TavilyTimeRangeInput =
+  | TavilyTimeRange
+  | 'h'
+  | 'd'
+  | 'w'
+  | 'm'
+  | 'y';
+
+export interface TavilySearchOptions {
+  searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
+  maxResults?: number;
+  includeImages?: boolean;
+  includeAnswer?: boolean | 'basic' | 'advanced';
+  includeRawContent?: boolean | 'markdown' | 'text';
+  includeDomains?: string[];
+  excludeDomains?: string[];
+  topic?: 'general' | 'news' | 'finance';
+  timeRange?: TavilyTimeRangeInput;
+  includeImageDescriptions?: boolean;
+  includeFavicon?: boolean;
+  chunksPerSource?: number;
+  safeSearch?: boolean;
+  timeout?: number;
+}
+
+export interface TavilySearchPayload {
+  query: string;
+  search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
+  topic: NonNullable<TavilySearchOptions['topic']>;
+  max_results: number;
+  safe_search?: boolean;
+  time_range?: TavilyTimeRange;
+  country?: string;
+  include_images?: boolean;
+  include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
+  include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
+  include_domains?: string[];
+  exclude_domains?: string[];
+  include_image_descriptions?: boolean;
+  include_favicon?: boolean;
+  chunks_per_source?: number;
+}
+
 export interface SearchConfig {
   searchProvider?: SearchProvider;
   serperApiKey?: string;
   searxngInstanceUrl?: string;
   searxngApiKey?: string;
+  tavilyApiKey?: string;
+  tavilySearchUrl?: string;
+  tavilyExtractUrl?: string;
+  tavilySearchOptions?: TavilySearchOptions;
 }
 
 export type References = {
@@ -106,6 +154,17 @@ export interface SerperScraperConfig {
   includeMarkdown?: boolean;
 }
 
+export interface TavilyScraperConfig {
+  apiKey?: string;
+  apiUrl?: string;
+  timeout?: number;
+  logger?: Logger;
+  extractDepth?: 'basic' | 'advanced';
+  includeImages?: boolean;
+  includeFavicon?: boolean;
+  format?: 'markdown' | 'text';
+}
+
 export interface ScraperContentResult {
   content: string;
 }
@@ -154,6 +213,7 @@ export interface SearchToolConfig
   extends SearchConfig,
     ProcessSourcesConfig,
     FirecrawlConfig {
+  tavilyScraperOptions?: TavilyScraperConfig;
   logger?: Logger;
   safeSearch?: SafeSearchLevel;
   jinaApiKey?: string;
@@ -181,20 +241,27 @@ export type UsedReferences = {
   reference: MediaReference;
 }[];
 
+export type AnyScraperResponse =
+  | FirecrawlScrapeResponse
+  | SerperScrapeResponse
+  | TavilyScrapeResponse;
+
 /** Base Scraper Interface */
 export interface BaseScraper {
   scrapeUrl(
     url: string,
     options?: unknown
-  ): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
+  ): Promise<[string, AnyScraperResponse]>;
+  scrapeUrls?(
+    urls: string[],
+    options?: unknown
+  ): Promise<Array<[string, AnyScraperResponse]>>;
   extractContent(
-    response: FirecrawlScrapeResponse | SerperScrapeResponse
+    response: AnyScraperResponse
   ): [string, undefined | References];
   extractMetadata(
-    response: FirecrawlScrapeResponse | SerperScrapeResponse
-  ):
-    | ScrapeMetadata
-    | Record<string, string | number | boolean | null | undefined>;
+    response: AnyScraperResponse
+  ): ScrapeMetadata | GenericScrapeMetadata;
 }
 
 /** Firecrawl */
@@ -208,6 +275,25 @@ export type SerperScrapeOptions = Omit<
   'apiKey' | 'apiUrl' | 'logger'
 >;
 
+export type TavilyScrapeOptions = Omit<
+  TavilyScraperConfig,
+  'apiKey' | 'apiUrl' | 'logger'
+>;
+
+export interface TavilyExtractPayload {
+  urls: string[];
+  extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
+  include_images: boolean;
+  include_favicon?: boolean;
+  format?: NonNullable<TavilyScraperConfig['format']>;
+  timeout?: number;
+}
+
+export type GenericScrapeMetadata = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
 export interface ScrapeMetadata {
   // Core source information
   sourceURL?: string;
@@ -294,6 +380,45 @@ export interface SerperScrapeResponse {
   error?: string;
 }
 
+export interface TavilyScrapeResponse {
+  success: boolean;
+  data?: {
+    rawContent?: string;
+    images?: string[];
+    favicon?: string;
+  };
+  error?: string;
+}
+
+export interface TavilySearchResult {
+  title?: string;
+  url?: string;
+  content?: string;
+  score?: number;
+  published_date?: string;
+}
+
+export type TavilyImageResult =
+  | string
+  | {
+      url?: string;
+      description?: string;
+    };
+
+export interface TavilySearchResponse {
+  answer?: string;
+  images?: TavilyImageResult[];
+  results?: TavilySearchResult[];
+}
+
+export interface TavilyExtractResult {
+  url: string;
+  raw_content?: string;
+  images?: string[];
+  favicon?: string;
+  error?: string;
+}
+
 export interface FirecrawlScraperConfig {
   apiKey?: string;
   apiUrl?: string;

package/src/tools/search/utils.ts

@@ -29,11 +29,18 @@ export const fileExtRegex =
 
 export const getDomainName = (
   link: string,
-  metadata?: t.ScrapeMetadata,
+  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
   logger?: t.Logger
 ): string | undefined => {
   try {
-    const url = metadata?.sourceURL ?? metadata?.url ?? (link || '');
+    const sourceUrl = metadata?.sourceURL;
+    const metadataUrl = metadata?.url;
+    const url =
+      typeof sourceUrl === 'string'
+        ? sourceUrl
+        : typeof metadataUrl === 'string'
+          ? metadataUrl
+          : link || '';
     const domain = new URL(url).hostname.replace(/^www\./, '');
     if (domain) {
       return domain;
@@ -52,7 +59,7 @@ export const getDomainName = (
 
 export function getAttribution(
   link: string,
-  metadata?: t.ScrapeMetadata,
+  metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata,
   logger?: t.Logger
 ): string | undefined {
   if (!metadata) return getDomainName(link, metadata, logger);
@@ -60,16 +67,17 @@ export function getAttribution(
   const twitterSite = metadata['twitter:site'];
   const twitterSiteFormatted =
     typeof twitterSite === 'string' ? twitterSite.replace(/^@/, '') : undefined;
+  const title = metadata.title;
 
   const possibleAttributions = [
     metadata.ogSiteName,
     metadata['og:site_name'],
-    metadata.title?.split('|').pop()?.trim(),
+    typeof title === 'string' ? title.split('|').pop()?.trim() : undefined,
     twitterSiteFormatted,
   ];
 
   const attribution = possibleAttributions.find(
-    (attr) => attr != null && typeof attr === 'string' && attr.trim() !== ''
+    (attr): attr is string => typeof attr === 'string' && attr.trim() !== ''
   );
   if (attribution != null) {
     return attribution;

package/src/types/graph.ts

@@ -1,14 +1,5 @@
 // src/types/graph.ts
-import type {
-  START,
-  StateType,
-  UpdateType,
-  StateGraph,
-  StateGraphArgs,
-  StateDefinition,
-  CompiledStateGraph,
-  BinaryOperatorAggregate,
-} from '@langchain/langgraph';
+import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type {
   BaseMessage,
@@ -129,76 +120,40 @@ export type Workflow<
   N extends string = string,
 > = StateGraph<T, U, N>;
 
-export type CompiledWorkflow<
-  T extends BaseGraphState = BaseGraphState,
-  U extends Partial<T> = Partial<T>,
-  N extends string = string,
-> = CompiledStateGraph<T, U, N>;
-
-export type CompiledStateWorkflow = CompiledStateGraph<
-  StateType<{
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  }>,
-  UpdateType<{
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  }>,
-  string,
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  },
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  },
-  StateDefinition
+type LangChainEventStreamCallbackHandlerInput = NonNullable<
+  Parameters<Runnable['streamEvents']>[2]
 >;
 
-export type CompiledMultiAgentWorkflow = CompiledStateGraph<
-  StateType<{
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  }>,
-  UpdateType<{
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  }>,
-  string,
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  },
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-  },
-  StateDefinition
->;
+export type EventStreamCallbackHandlerInput =
+  LangChainEventStreamCallbackHandlerInput & {
+    autoClose?: boolean;
+    raiseError?: boolean;
+    ignoreCustomEvent?: boolean;
+  };
 
-export type CompiledAgentWorfklow = CompiledStateGraph<
+export type WorkflowValuesStreamConfig = RunnableConfig & {
+  streamMode: 'values';
+};
+
+/**
+ * LangGraph stream output is mode-dependent (`values`, `updates`, SSE, etc.).
+ * Keep the base Runnable stream output as unknown and narrow at callsites that
+ * choose a concrete streamMode.
+ */
+export type CompiledWorkflow<
+  TInput extends BaseGraphState = BaseGraphState,
+  TOutput extends BaseGraphState = TInput,
+> = Omit<Runnable<TInput, unknown>, 'invoke'> & {
+  invoke(input: TInput, config?: RunnableConfig): Promise<TOutput>;
+};
+
+export type CompiledStateWorkflow = CompiledWorkflow;
+
+export type CompiledMultiAgentWorkflow = CompiledWorkflow<MultiAgentGraphState>;
+
+export type CompiledAgentWorfklow = CompiledWorkflow<
   AgentSubgraphState,
-  Partial<AgentSubgraphState>,
-  '__start__' | `agent=${string}` | `tools=${string}` | `summarize=${string}`,
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    summarizationRequest: BinaryOperatorAggregate<
-      SummarizationNodeInput | undefined,
-      SummarizationNodeInput | undefined
-    >;
-  },
-  {
-    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
-    summarizationRequest: BinaryOperatorAggregate<
-      SummarizationNodeInput | undefined,
-      SummarizationNodeInput | undefined
-    >;
-  },
-  StateDefinition,
-  {
-    [x: `agent=${string}`]: Partial<BaseGraphState>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [x: `tools=${string}`]: any;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [x: `summarize=${string}`]: any;
-  }
+  AgentSubgraphState
 >;
 
 export type SystemRunnable =
@@ -214,21 +169,11 @@ export type SystemRunnable =
  * These are intentionally untyped to avoid coupling to library internals.
  */
 export type CompileOptions = {
-  // A checkpointer instance (e.g., MemorySaver, SQL saver)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  checkpointer?: any;
+  checkpointer?: unknown;
   interruptBefore?: string[];
   interruptAfter?: string[];
 };
 
-export type EventStreamCallbackHandlerInput =
-  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<
-    infer T,
-    'autoClose'
-  >
-    ? T
-    : never;
-
 export type StreamChunk =
   | (ChatGenerationChunk & {
       message: AIMessageChunk;