@librechat/agents 2.4.322 → 3.0.0-rc1

package/src/tools/handlers.ts

@@ -1,21 +1,36 @@
 /* eslint-disable no-console */
 // src/tools/handlers.ts
 import { nanoid } from 'nanoid';
+import { ToolMessage } from '@langchain/core/messages';
+import type { AnthropicWebSearchResultBlockParam } from '@/llm/anthropic/types';
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
-import type { Graph } from '@/graphs';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { AgentContext } from '@/agents/AgentContext';
 import type * as t from '@/types';
-import { StepTypes, ContentTypes, ToolCallTypes } from '@/common';
+import {
+  ToolCallTypes,
+  ContentTypes,
+  GraphEvents,
+  StepTypes,
+  Providers,
+  Constants,
+} from '@/common';
+import {
+  coerceAnthropicSearchResults,
+  isAnthropicWebSearchResult,
+} from '@/tools/search/anthropic';
+import { formatResultsForLLM } from '@/tools/search/format';
 import { getMessageId } from '@/messages';
 
-export function handleToolCallChunks({
+export async function handleToolCallChunks({
   graph,
   stepKey,
   toolCallChunks,
 }: {
-  graph: Graph;
+  graph: StandardGraph | MultiAgentGraph;
   stepKey: string;
   toolCallChunks: ToolCallChunk[];
-}): void {
+}): Promise<void> {
   let prevStepId: string;
   let prevRunStep: t.RunStep | undefined;
   try {
@@ -24,7 +39,7 @@ export function handleToolCallChunks({
   } catch {
     /** Edge Case: If no previous step exists, create a new message creation step */
     const message_id = getMessageId(stepKey, graph, true) ?? '';
-    prevStepId = graph.dispatchRunStep(stepKey, {
+    prevStepId = await graph.dispatchRunStep(stepKey, {
       type: StepTypes.MESSAGE_CREATION,
       message_creation: {
         message_id,
@@ -67,7 +82,7 @@ export function handleToolCallChunks({
     prevRunStep?.type === StepTypes.MESSAGE_CREATION &&
     graph.messageStepHasToolCalls.has(prevStepId);
   if (!alreadyDispatched && tool_calls?.length === toolCallChunks.length) {
-    graph.dispatchMessageDelta(prevStepId, {
+    await graph.dispatchMessageDelta(prevStepId, {
       content: [
         {
           type: ContentTypes.TEXT,
@@ -77,22 +92,22 @@ export function handleToolCallChunks({
       ],
     });
     graph.messageStepHasToolCalls.set(prevStepId, true);
-    stepId = graph.dispatchRunStep(stepKey, {
+    stepId = await graph.dispatchRunStep(stepKey, {
       type: StepTypes.TOOL_CALLS,
       tool_calls,
     });
   }
-  graph.dispatchRunStepDelta(stepId, {
+  await graph.dispatchRunStepDelta(stepId, {
     type: StepTypes.TOOL_CALLS,
     tool_calls: toolCallChunks,
   });
 }
 
-export const handleToolCalls = (
+export const handleToolCalls = async (
   toolCalls?: ToolCall[],
   metadata?: Record<string, unknown>,
-  graph?: Graph
-): void => {
+  graph?: StandardGraph | MultiAgentGraph
+): Promise<void> => {
   if (!graph || !metadata) {
     console.warn(`Graph or metadata not found in ${event} event`);
     return;
@@ -124,8 +139,10 @@ export const handleToolCalls = (
       // no previous step
     }
 
-    const dispatchToolCallIds = (lastMessageStepId: string): void => {
-      graph.dispatchMessageDelta(lastMessageStepId, {
+    const dispatchToolCallIds = async (
+      lastMessageStepId: string
+    ): Promise<void> => {
+      await graph.dispatchMessageDelta(lastMessageStepId, {
         content: [
           {
             type: 'text',
@@ -141,7 +158,7 @@ export const handleToolCalls = (
       prevRunStep &&
       prevRunStep.type === StepTypes.MESSAGE_CREATION
     ) {
-      dispatchToolCallIds(prevStepId);
+      await dispatchToolCallIds(prevStepId);
       graph.messageStepHasToolCalls.set(prevStepId, true);
       /* If the previous step doesn't exist or is not a message creation */
     } else if (
@@ -149,19 +166,176 @@ export const handleToolCalls = (
       prevRunStep.type !== StepTypes.MESSAGE_CREATION
     ) {
       const messageId = getMessageId(stepKey, graph, true) ?? '';
-      const stepId = graph.dispatchRunStep(stepKey, {
+      const stepId = await graph.dispatchRunStep(stepKey, {
         type: StepTypes.MESSAGE_CREATION,
         message_creation: {
           message_id: messageId,
         },
       });
-      dispatchToolCallIds(stepId);
+      await dispatchToolCallIds(stepId);
       graph.messageStepHasToolCalls.set(prevStepId, true);
     }
 
-    graph.dispatchRunStep(stepKey, {
+    await graph.dispatchRunStep(stepKey, {
       type: StepTypes.TOOL_CALLS,
       tool_calls: [tool_call],
     });
   }
 };
+
+export const toolResultTypes = new Set([
+  // 'tool_use',
+  // 'server_tool_use',
+  // 'input_json_delta',
+  'tool_result',
+  'web_search_result',
+  'web_search_tool_result',
+]);
+
+/**
+ * Handles the result of a server tool call; in other words, a provider's built-in tool.
+ * As of 2025-07-06, only Anthropic handles server tool calls with this pattern.
+ */
+export async function handleServerToolResult({
+  graph,
+  content,
+  metadata,
+  agentContext,
+}: {
+  graph: StandardGraph | MultiAgentGraph;
+  content?: string | t.MessageContentComplex[];
+  metadata?: Record<string, unknown>;
+  agentContext?: AgentContext;
+}): Promise<boolean> {
+  let skipHandling = false;
+  if (agentContext?.provider !== Providers.ANTHROPIC) {
+    return skipHandling;
+  }
+  if (
+    typeof content === 'string' ||
+    content == null ||
+    content.length === 0 ||
+    (content.length === 1 &&
+      (content[0] as t.ToolResultContent).tool_use_id == null)
+  ) {
+    return skipHandling;
+  }
+
+  for (const contentPart of content) {
+    const toolUseId = (contentPart as t.ToolResultContent).tool_use_id;
+    if (toolUseId == null || toolUseId === '') {
+      continue;
+    }
+    const stepId = graph.toolCallStepIds.get(toolUseId);
+    if (stepId == null || stepId === '') {
+      console.warn(
+        `Tool use ID ${toolUseId} not found in graph, cannot dispatch tool result.`
+      );
+      continue;
+    }
+    const runStep = graph.getRunStep(stepId);
+    if (!runStep) {
+      console.warn(
+        `Run step for ${stepId} does not exist, cannot dispatch tool result.`
+      );
+      continue;
+    } else if (runStep.type !== StepTypes.TOOL_CALLS) {
+      console.warn(
+        `Run step for ${stepId} is not a tool call step, cannot dispatch tool result.`
+      );
+      continue;
+    }
+
+    const toolCall =
+      runStep.stepDetails.type === StepTypes.TOOL_CALLS
+        ? (runStep.stepDetails.tool_calls?.find(
+          (toolCall) => toolCall.id === toolUseId
+        ) as ToolCall)
+        : undefined;
+
+    if (!toolCall) {
+      continue;
+    }
+
+    if (
+      contentPart.type === 'web_search_result' ||
+      contentPart.type === 'web_search_tool_result'
+    ) {
+      await handleAnthropicSearchResults({
+        contentPart: contentPart as t.ToolResultContent,
+        toolCall,
+        metadata,
+        graph,
+      });
+    }
+
+    if (!skipHandling) {
+      skipHandling = true;
+    }
+  }
+
+  return skipHandling;
+}
+
+async function handleAnthropicSearchResults({
+  contentPart,
+  toolCall,
+  metadata,
+  graph,
+}: {
+  contentPart: t.ToolResultContent;
+  toolCall: Partial<ToolCall>;
+  metadata?: Record<string, unknown>;
+  graph: StandardGraph | MultiAgentGraph;
+}): Promise<void> {
+  if (!Array.isArray(contentPart.content)) {
+    console.warn(
+      `Expected content to be an array, got ${typeof contentPart.content}`
+    );
+    return;
+  }
+
+  if (!isAnthropicWebSearchResult(contentPart.content[0])) {
+    console.warn(
+      `Expected content to be an Anthropic web search result, got ${JSON.stringify(
+        contentPart.content
+      )}`
+    );
+    return;
+  }
+
+  const turn = graph.invokedToolIds?.size ?? 0;
+  const searchResultData = coerceAnthropicSearchResults({
+    turn,
+    results: contentPart.content as AnthropicWebSearchResultBlockParam[],
+  });
+
+  const name = toolCall.name;
+  const input = toolCall.args ?? {};
+  const artifact = {
+    [Constants.WEB_SEARCH]: searchResultData,
+  };
+  const { output: formattedOutput } = formatResultsForLLM(
+    turn,
+    searchResultData
+  );
+  const output = new ToolMessage({
+    name,
+    artifact,
+    content: formattedOutput,
+    tool_call_id: toolCall.id!,
+  });
+  const toolEndData: t.ToolEndData = {
+    input,
+    output,
+  };
+  await graph.handlerRegistry
+    ?.getHandler(GraphEvents.TOOL_END)
+    ?.handle(GraphEvents.TOOL_END, toolEndData, metadata, graph);
+
+  if (graph.invokedToolIds == null) {
+    graph.invokedToolIds = new Set<string>();
+  }
+
+  graph.invokedToolIds.add(toolCall.id!);
+}

package/src/tools/search/anthropic.ts

@@ -0,0 +1,51 @@
+import type {
+  AnthropicTextBlockParam,
+  AnthropicWebSearchResultBlockParam,
+} from '@/llm/anthropic/types';
+import type { SearchResultData, ProcessedOrganic } from './types';
+import { getAttribution } from './utils';
+
+/**
+ * Coerces Anthropic web search results to the SearchResultData format
+ * @param results - Array of Anthropic web search results
+ * @param turn - The turn number to associate with these results
+ * @returns SearchResultData with minimal ProcessedOrganic items
+ */
+export function coerceAnthropicSearchResults({
+  results,
+  turn = 0,
+}: {
+  results: (AnthropicTextBlockParam | AnthropicWebSearchResultBlockParam)[];
+  turn?: number;
+}): SearchResultData {
+  const organic: ProcessedOrganic[] = results
+    .filter((result) => result.type === 'web_search_result')
+    .map((result, index) => ({
+      link: result.url,
+      position: index + 1,
+      title: result.title,
+      date: result.page_age ?? undefined,
+      attribution: getAttribution(result.url),
+    }));
+
+  return {
+    turn,
+    organic,
+  };
+}
+
+/**
+ * Helper function to check if an object is an Anthropic web search result
+ */
+export function isAnthropicWebSearchResult(
+  obj: unknown
+): obj is AnthropicWebSearchResultBlockParam {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'type' in obj &&
+    obj.type === 'web_search_result' &&
+    'url' in obj &&
+    typeof (obj as Record<string, unknown>).url === 'string'
+  );
+}

package/src/tools/search/firecrawl.ts

@@ -13,6 +13,21 @@ export class FirecrawlScraper {
   private defaultFormats: string[];
   private timeout: number;
   private logger: t.Logger;
+  private includeTags?: string[];
+  private excludeTags?: string[];
+  private waitFor?: number;
+  private maxAge?: number;
+  private mobile?: boolean;
+  private skipTlsVerification?: boolean;
+  private blockAds?: boolean;
+  private removeBase64Images?: boolean;
+  private parsePDF?: boolean;
+  private storeInCache?: boolean;
+  private zeroDataRetention?: boolean;
+  private headers?: Record<string, string>;
+  private location?: { country?: string; languages?: string[] };
+  private onlyMainContent?: boolean;
+  private changeTrackingOptions?: object;
 
   constructor(config: t.FirecrawlScraperConfig = {}) {
     this.apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY ?? '';
@@ -23,11 +38,27 @@ export class FirecrawlScraper {
       'https://api.firecrawl.dev';
     this.apiUrl = `${baseUrl.replace(/\/+$/, '')}/v1/scrape`;
 
-    this.defaultFormats = config.formats ?? ['markdown', 'html'];
-    this.timeout = config.timeout ?? 15000;
+    this.defaultFormats = config.formats ?? ['markdown', 'rawHtml'];
+    this.timeout = config.timeout ?? 7500;
 
     this.logger = config.logger || createDefaultLogger();
 
+    this.includeTags = config.includeTags;
+    this.excludeTags = config.excludeTags;
+    this.waitFor = config.waitFor;
+    this.maxAge = config.maxAge;
+    this.mobile = config.mobile;
+    this.skipTlsVerification = config.skipTlsVerification;
+    this.blockAds = config.blockAds;
+    this.removeBase64Images = config.removeBase64Images;
+    this.parsePDF = config.parsePDF;
+    this.storeInCache = config.storeInCache;
+    this.zeroDataRetention = config.zeroDataRetention;
+    this.headers = config.headers;
+    this.location = config.location;
+    this.onlyMainContent = config.onlyMainContent;
+    this.changeTrackingOptions = config.changeTrackingOptions;
+
     if (!this.apiKey) {
       this.logger.warn('FIRECRAWL_API_KEY is not set. Scraping will not work.');
     }
@@ -58,25 +89,36 @@ export class FirecrawlScraper {
     }
 
     try {
-      const response = await axios.post(
-        this.apiUrl,
-        {
-          url,
-          formats: options.formats || this.defaultFormats,
-          includeTags: options.includeTags,
-          excludeTags: options.excludeTags,
-          headers: options.headers,
-          waitFor: options.waitFor,
-          timeout: options.timeout ?? this.timeout,
+      const payload = omitUndefined({
+        url,
+        formats: options.formats ?? this.defaultFormats,
+        includeTags: options.includeTags ?? this.includeTags,
+        excludeTags: options.excludeTags ?? this.excludeTags,
+        headers: options.headers ?? this.headers,
+        waitFor: options.waitFor ?? this.waitFor,
+        timeout: options.timeout ?? this.timeout,
+        onlyMainContent: options.onlyMainContent ?? this.onlyMainContent,
+        maxAge: options.maxAge ?? this.maxAge,
+        mobile: options.mobile ?? this.mobile,
+        skipTlsVerification:
+          options.skipTlsVerification ?? this.skipTlsVerification,
+        parsePDF: options.parsePDF ?? this.parsePDF,
+        location: options.location ?? this.location,
+        removeBase64Images:
+          options.removeBase64Images ?? this.removeBase64Images,
+        blockAds: options.blockAds ?? this.blockAds,
+        storeInCache: options.storeInCache ?? this.storeInCache,
+        zeroDataRetention: options.zeroDataRetention ?? this.zeroDataRetention,
+        changeTrackingOptions:
+          options.changeTrackingOptions ?? this.changeTrackingOptions,
+      });
+      const response = await axios.post(this.apiUrl, payload, {
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.apiKey}`,
         },
-        {
-          headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${this.apiKey}`,
-          },
-          timeout: this.timeout,
-        }
-      );
+        timeout: this.timeout,
+      });
 
       return [url, response.data];
     } catch (error) {
@@ -156,3 +198,10 @@ export const createFirecrawlScraper = (
 ): FirecrawlScraper => {
   return new FirecrawlScraper(config);
 };
+
+// Helper function to clean up payload for firecrawl
+function omitUndefined<T extends object>(obj: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== undefined)
+  ) as Partial<T>;
+}

package/src/tools/search/format.ts

@@ -65,6 +65,12 @@ function formatSource(
           if (ref.reference.originalUrl.includes('mailto:')) {
             continue;
           }
+          if (ref.type !== 'link') {
+            continue;
+          }
+          if (fileExtRegex.test(ref.reference.originalUrl)) {
+            continue;
+          }
           references.push({
             type: ref.type,
             link: ref.reference.originalUrl,
@@ -75,14 +81,6 @@ function formatSource(
             ).split('\n')[0],
           });
 
-          if (ref.type !== 'link') {
-            continue;
-          }
-
-          if (fileExtRegex.test(ref.reference.originalUrl)) {
-            continue;
-          }
-
           if (!hasHeader) {
             refLines.push('Core References:');
             hasHeader = true;

package/src/tools/search/rerankers.ts

@@ -25,13 +25,6 @@ export abstract class BaseReranker {
       .slice(0, Math.min(topK, documents.length))
       .map((doc) => ({ text: doc, score: 0 }));
   }
-
-  protected logDocumentSamples(documents: string[]): void {
-    this.logger.debug('Sample documents being sent to API:');
-    for (let i = 0; i < Math.min(3, documents.length); i++) {
-      this.logger.debug(`Document ${i}: ${documents[i].substring(0, 100)}...`);
-    }
-  }
 }
 
 export class JinaReranker extends BaseReranker {
@@ -51,7 +44,7 @@ export class JinaReranker extends BaseReranker {
     documents: string[],
     topK: number = 5
   ): Promise<t.Highlight[]> {
-    this.logger.debug(`Reranking ${documents.length} documents with Jina`);
+    this.logger.debug(`Reranking ${documents.length} chunks with Jina`);
 
     try {
       if (this.apiKey == null || this.apiKey === '') {
@@ -59,8 +52,6 @@ export class JinaReranker extends BaseReranker {
         return this.getDefaultRanking(documents, topK);
       }
 
-      this.logDocumentSamples(documents);
-
       const requestData = {
         model: 'jina-reranker-v2-base-multilingual',
         query: query,
@@ -80,19 +71,8 @@ export class JinaReranker extends BaseReranker {
         }
       );
 
-      // Log the response data structure
-      this.logger.debug('Jina API response structure:');
-      this.logger.debug('Model:', response.data?.model);
-      this.logger.debug('Usage:', response.data?.usage);
-      this.logger.debug('Results count:', response.data?.results.length);
-
-      // Log a sample of the results
-      if ((response.data?.results.length ?? 0) > 0) {
-        this.logger.debug(
-          'Sample result:',
-          JSON.stringify(response.data?.results[0], null, 2)
-        );
-      }
+      this.logger.debug('Jina API Model:', response.data?.model);
+      this.logger.debug('Jina API Usage:', response.data?.usage);
 
       if (response.data && response.data.results.length) {
         return response.data.results.map((result) => {
@@ -146,7 +126,7 @@ export class CohereReranker extends BaseReranker {
     documents: string[],
     topK: number = 5
   ): Promise<t.Highlight[]> {
-    this.logger.debug(`Reranking ${documents.length} documents with Cohere`);
+    this.logger.debug(`Reranking ${documents.length} chunks with Cohere`);
 
     try {
       if (this.apiKey == null || this.apiKey === '') {
@@ -154,8 +134,6 @@ export class CohereReranker extends BaseReranker {
         return this.getDefaultRanking(documents, topK);
       }
 
-      this.logDocumentSamples(documents);
-
       const requestData = {
         model: 'rerank-v3.5',
         query: query,
@@ -174,19 +152,8 @@ export class CohereReranker extends BaseReranker {
         }
       );
 
-      // Log the response data structure
-      this.logger.debug('Cohere API response structure:');
-      this.logger.debug('ID:', response.data?.id);
-      this.logger.debug('Meta:', response.data?.meta);
-      this.logger.debug('Results count:', response.data?.results.length);
-
-      // Log a sample of the results
-      if ((response.data?.results.length ?? 0) > 0) {
-        this.logger.debug(
-          'Sample result:',
-          JSON.stringify(response.data?.results[0], null, 2)
-        );
-      }
+      this.logger.debug('Cohere API ID:', response.data?.id);
+      this.logger.debug('Cohere API Meta:', response.data?.meta);
 
       if (response.data && response.data.results.length) {
         return response.data.results.map((result) => {
@@ -221,7 +188,7 @@ export class InfinityReranker extends BaseReranker {
     topK: number = 5
   ): Promise<t.Highlight[]> {
     this.logger.debug(
-      `Reranking ${documents.length} documents with Infinity (placeholder)`
+      `Reranking ${documents.length} chunks with Infinity (placeholder)`
     );
     // This would be replaced with actual Infinity reranker implementation
     return this.getDefaultRanking(documents, topK);