⏲️ feat: Defer Loading MCP Tools (#11270)

* WIP: code ptc

* refactor: tool classification and calling logic

* 🔧 fix: Update @librechat/agents dependency to version 3.0.68

* chore: import order and correct renamed tool name for tool search

* refactor: streamline tool classification logic for local and programmatic tools

* feat: add per-tool configuration options for agents, including deferred loading and allowed callers

- Introduced `tool_options` in agent forms to manage tool behavior.
- Updated tool classification logic to prioritize agent-level configurations.
- Enhanced UI components to support tool deferral functionality.
- Added localization strings for new tool options and actions.

* feat: enhance agent schema with per-tool options for configuration

- Added `tool_options` schema to support per-tool configurations, including `defer_loading` and `allowed_callers`.
- Updated agent data model to incorporate new tool options, ensuring flexibility in tool behavior management.
- Modified type definitions to reflect the new `tool_options` structure for agents.

* feat: add tool_options parameter to loadTools and initializeAgent for enhanced agent configuration

* chore: update @librechat/agents dependency to version 3.0.71 and enhance agent tool loading logic

- Updated the @librechat/agents package to version 3.0.71 across multiple files.
- Added support for handling deferred loading of tools in agent initialization and execution processes.
- Improved the extraction of discovered tools from message history to optimize tool loading behavior.

* chore: update @librechat/agents dependency to version 3.0.72

* chore: update @librechat/agents dependency to version 3.0.75

* refactor: simplify tool defer loading logic in MCPTool component

- Removed local state management for deferred tools, relying on form state instead.
- Updated related functions to directly use form values for checking and toggling defer loading.
- Cleaned up code by eliminating unnecessary optimistic updates and local state dependencies.

* chore: remove deprecated localization strings for tool deferral in translation.json

- Eliminated unused strings related to deferred loading descriptions in the English translation file.
- Streamlined localization to reflect recent changes in tool loading logic.

* refactor: improve tool defer loading handling in MCPTool component

- Enhanced the logic for managing deferred loading of tools by simplifying the update process for tool options.
- Ensured that the state reflects the correct loading behavior based on the new deferred loading conditions.
- Cleaned up the code to remove unnecessary complexity in handling tool options.

* refactor: update agent mocks in callbacks test to use actual implementations

- Modified the agent mocks in the callbacks test to include actual implementations from the @librechat/agents module.
- This change enhances the accuracy of the tests by ensuring they reflect the real behavior of the agent functions.

packages/api/src/agents/initialize.ts

@@ -10,14 +10,15 @@ import {
 } from 'librechat-data-provider';
 import type {
   AgentToolResources,
+  AgentToolOptions,
   TEndpointOption,
   TFile,
   Agent,
   TUser,
 } from 'librechat-data-provider';
+import type { GenericTool, LCToolRegistry, ToolMap } from '@librechat/agents';
 import type { Response as ServerResponse } from 'express';
 import type { IMongoFile } from '@librechat/data-schemas';
-import type { GenericTool } from '@librechat/agents';
 import type { InitializeResultBase, ServerRequest, EndpointDbMethods } from '~/types';
 import { getModelMaxTokens, extractLibreChatParams, optionalChainWithEmptyCheck } from '~/utils';
 import { filterFilesByEndpointConfig } from '~/files';
@@ -36,6 +37,12 @@ export type InitializedAgent = Agent & {
   useLegacyContent: boolean;
   resendFiles: boolean;
   userMCPAuthMap?: Record<string, Record<string, string>>;
+  /** Tool map for ToolNode to use when executing tools (required for PTC) */
+  toolMap?: ToolMap;
+  /** Tool registry for PTC and tool search (only present when MCP tools with env classification exist) */
+  toolRegistry?: LCToolRegistry;
+  /** Precomputed flag indicating if any tools have defer_loading enabled (for efficient runtime checks) */
+  hasDeferredTools?: boolean;
 };
 
 /**
@@ -61,11 +68,14 @@ export interface InitializeAgentParams {
     agentId: string;
     tools: string[];
     model: string | null;
+    tool_options: AgentToolOptions | undefined;
     tool_resources: AgentToolResources | undefined;
   }) => Promise<{
     tools: GenericTool[];
     toolContextMap: Record<string, unknown>;
     userMCPAuthMap?: Record<string, Record<string, string>>;
+    toolRegistry?: LCToolRegistry;
+    hasDeferredTools?: boolean;
   } | null>;
   /** Endpoint option (contains model_parameters and endpoint info) */
   endpointOption?: Partial<TEndpointOption>;
@@ -201,6 +211,8 @@ export async function initializeAgent(
     tools: structuredTools,
     toolContextMap,
     userMCPAuthMap,
+    toolRegistry,
+    hasDeferredTools,
   } = (await loadTools?.({
     req,
     res,
@@ -208,8 +220,15 @@ export async function initializeAgent(
     agentId: agent.id,
     tools: agent.tools ?? [],
     model: agent.model,
+    tool_options: agent.tool_options,
     tool_resources,
-  })) ?? { tools: [], toolContextMap: {}, userMCPAuthMap: undefined };
+  })) ?? {
+    tools: [],
+    toolContextMap: {},
+    userMCPAuthMap: undefined,
+    toolRegistry: undefined,
+    hasDeferredTools: false,
+  };
 
   const { getOptions, overrideProvider } = getProviderConfig({
     provider,
@@ -312,6 +331,8 @@ export async function initializeAgent(
     attachments: finalAttachments,
     resendFiles,
     userMCPAuthMap,
+    toolRegistry,
+    hasDeferredTools,
     toolContextMap: toolContextMap ?? {},
     useLegacyContent: !!options.useLegacyContent,
     maxContextTokens: Math.round((agentMaxContextNum - maxOutputTokensNum) * 0.9),

packages/api/src/agents/run.ts

@@ -1,9 +1,11 @@
 import { Run, Providers } from '@librechat/agents';
 import { providerEndpointMap, KnownEndpoints } from 'librechat-data-provider';
+import type { BaseMessage } from '@langchain/core/messages';
 import type {
   MultiAgentGraphConfig,
   OpenAIClientOptions,
   StandardGraphConfig,
+  LCToolRegistry,
   AgentInputs,
   GenericTool,
   RunConfig,
@@ -14,6 +16,121 @@ import type { Agent } from 'librechat-data-provider';
 import type * as t from '~/types';
 import { resolveHeaders, createSafeUser } from '~/utils/env';
 
+/** Tool search tool name constant */
+const TOOL_SEARCH_NAME = 'tool_search';
+
+/** Expected shape of JSON tool search results */
+interface ToolSearchJsonResult {
+  found?: number;
+  tools?: Array<{ name: string }>;
+}
+
+/**
+ * Parses tool names from JSON-formatted tool_search output.
+ * Format: { "found": N, "tools": [{ "name": "tool_name", ... }], ... }
+ *
+ * @param content - The JSON string content
+ * @param discoveredTools - Set to add discovered tool names to
+ * @returns true if parsing succeeded, false otherwise
+ */
+function parseToolSearchJson(content: string, discoveredTools: Set<string>): boolean {
+  try {
+    const parsed = JSON.parse(content) as ToolSearchJsonResult;
+    if (!parsed.tools || !Array.isArray(parsed.tools)) {
+      return false;
+    }
+    for (const tool of parsed.tools) {
+      if (tool.name && typeof tool.name === 'string') {
+        discoveredTools.add(tool.name);
+      }
+    }
+    return parsed.tools.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parses tool names from legacy text-formatted tool_search output.
+ * Format: "- tool_name (score: X.XX)"
+ *
+ * @param content - The text content
+ * @param discoveredTools - Set to add discovered tool names to
+ */
+function parseToolSearchLegacy(content: string, discoveredTools: Set<string>): void {
+  const toolNameRegex = /^- ([^\s(]+)\s*\(score:/gm;
+  let match: RegExpExecArray | null;
+  while ((match = toolNameRegex.exec(content)) !== null) {
+    const toolName = match[1];
+    if (toolName) {
+      discoveredTools.add(toolName);
+    }
+  }
+}
+
+/**
+ * Extracts discovered tool names from message history by parsing tool_search results.
+ * When the LLM calls tool_search, the result contains tool names that were discovered.
+ * These tools should have defer_loading overridden to false on subsequent turns.
+ *
+ * Supports both:
+ * - New JSON format: { "tools": [{ "name": "tool_name" }] }
+ * - Legacy text format: "- tool_name (score: X.XX)"
+ *
+ * @param messages - The conversation message history
+ * @returns Set of tool names that were discovered via tool_search
+ */
+export function extractDiscoveredToolsFromHistory(messages: BaseMessage[]): Set<string> {
+  const discoveredTools = new Set<string>();
+
+  for (const message of messages) {
+    const msgType = message._getType?.() ?? message.constructor?.name ?? '';
+    if (msgType !== 'tool') {
+      continue;
+    }
+
+    const name = (message as { name?: string }).name;
+    if (name !== TOOL_SEARCH_NAME) {
+      continue;
+    }
+
+    const content = message.content;
+    if (typeof content !== 'string') {
+      continue;
+    }
+
+    /** Try JSON format first (new), fall back to regex (legacy) */
+    if (!parseToolSearchJson(content, discoveredTools)) {
+      parseToolSearchLegacy(content, discoveredTools);
+    }
+  }
+
+  return discoveredTools;
+}
+
+/**
+ * Overrides defer_loading to false for tools that were already discovered via tool_search.
+ * This prevents the LLM from having to re-discover tools on every turn.
+ *
+ * @param toolRegistry - The tool registry to modify (mutated in place)
+ * @param discoveredTools - Set of tool names that were previously discovered
+ * @returns Number of tools that had defer_loading overridden
+ */
+export function overrideDeferLoadingForDiscoveredTools(
+  toolRegistry: LCToolRegistry,
+  discoveredTools: Set<string>,
+): number {
+  let overrideCount = 0;
+  for (const toolName of discoveredTools) {
+    const toolDef = toolRegistry.get(toolName);
+    if (toolDef && toolDef.defer_loading === true) {
+      toolDef.defer_loading = false;
+      overrideCount++;
+    }
+  }
+  return overrideCount;
+}
+
 const customProviders = new Set([
   Providers.XAI,
   Providers.DEEPSEEK,
@@ -48,6 +165,9 @@ type RunAgent = Omit<Agent, 'tools'> & {
   maxContextTokens?: number;
   useLegacyContent?: boolean;
   toolContextMap?: Record<string, string>;
+  toolRegistry?: LCToolRegistry;
+  /** Precomputed flag indicating if any tools have defer_loading enabled */
+  hasDeferredTools?: boolean;
 };
 
 /**
@@ -60,12 +180,16 @@ type RunAgent = Omit<Agent, 'tools'> & {
  * @param options.customHandlers - Custom event handlers.
  * @param options.streaming - Whether to use streaming.
  * @param options.streamUsage - Whether to stream usage information.
+ * @param options.messages - Optional message history to extract discovered tools from.
+ *   When provided, tools that were previously discovered via tool_search will have
+ *   their defer_loading overridden to false, preventing redundant re-discovery.
  * @returns {Promise<Run<IState>>} A promise that resolves to a new Run instance.
  */
 export async function createRun({
   runId,
   signal,
   agents,
+  messages,
   requestBody,
   user,
   tokenCounter,
@@ -81,9 +205,26 @@ export async function createRun({
   streamUsage?: boolean;
   requestBody?: t.RequestBody;
   user?: IUser;
+  /** Message history for extracting previously discovered tools */
+  messages?: BaseMessage[];
 } & Pick<RunConfig, 'tokenCounter' | 'customHandlers' | 'indexTokenCountMap'>): Promise<
   Run<IState>
 > {
+  /**
+   * Only extract discovered tools if:
+   * 1. We have message history to parse
+   * 2. At least one agent has deferred tools (using precomputed flag)
+   *
+   * This optimization avoids iterating through messages in the ~95% of cases
+   * where no agent uses deferred tool loading.
+   */
+  const hasAnyDeferredTools = agents.some((agent) => agent.hasDeferredTools === true);
+
+  const discoveredTools =
+    hasAnyDeferredTools && messages?.length
+      ? extractDiscoveredToolsFromHistory(messages)
+      : new Set<string>();
+
   const agentInputs: AgentInputs[] = [];
   const buildAgentContext = (agent: RunAgent) => {
     const provider =
@@ -135,6 +276,14 @@ export async function createRun({
       llmConfig.usage = true;
     }
 
+    /**
+     * Override defer_loading for tools that were discovered in previous turns.
+     * This prevents the LLM from having to re-discover tools via tool_search.
+     */
+    if (discoveredTools.size > 0 && agent.toolRegistry) {
+      overrideDeferLoadingForDiscoveredTools(agent.toolRegistry, discoveredTools);
+    }
+
     const reasoningKey = getReasoningKey(provider, llmConfig, agent.endpoint);
     const agentInput: AgentInputs = {
       provider,
@@ -144,6 +293,7 @@ export async function createRun({
       tools: agent.tools,
       clientOptions: llmConfig,
       instructions: systemContent,
+      toolRegistry: agent.toolRegistry,
       maxContextTokens: agent.maxContextTokens,
       useLegacyContent: agent.useLegacyContent ?? false,
     };

packages/api/src/agents/validation.ts

@@ -51,6 +51,15 @@ export const graphEdgeSchema = z.object({
   promptKey: z.string().optional(),
 });
 
+/** Per-tool options schema (defer_loading, allowed_callers) */
+export const toolOptionsSchema = z.object({
+  defer_loading: z.boolean().optional(),
+  allowed_callers: z.array(z.enum(['direct', 'code_execution'])).optional(),
+});
+
+/** Agent tool options - map of tool_id to tool options */
+export const agentToolOptionsSchema = z.record(z.string(), toolOptionsSchema).optional();
+
 /** Base agent schema with all common fields */
 export const agentBaseSchema = z.object({
   name: z.string().nullable().optional(),
@@ -68,6 +77,7 @@ export const agentBaseSchema = z.object({
   recursion_limit: z.number().optional(),
   conversation_starters: z.array(z.string()).optional(),
   tool_resources: agentToolResourcesSchema,
+  tool_options: agentToolOptionsSchema,
   support_contact: agentSupportContactSchema,
   category: z.string().optional(),
 });