⏲️ 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),