@librechat/agents 3.1.1 → 3.1.21

package/dist/esm/tools/createSchemaOnlyTool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createSchemaOnlyTool.mjs","sources":["../../../src/tools/createSchemaOnlyTool.ts"],"sourcesContent":["import { tool, type StructuredToolInterface } from '@langchain/core/tools';\nimport type { LCTool } from '@/types';\n\n/**\n * Creates a schema-only tool for LLM binding in event-driven mode.\n * These tools have valid schemas for the LLM to understand but should\n * never be invoked directly - ToolNode handles execution via events.\n */\nexport function createSchemaOnlyTool(\n  definition: LCTool\n): StructuredToolInterface {\n  const { name, description, parameters, responseFormat } = definition;\n\n  return tool(\n    async () => {\n      throw new Error(\n        `Tool \"${name}\" should not be invoked directly in event-driven mode. ` +\n          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'\n      );\n    },\n    {\n      name,\n      description: description ?? '',\n      schema: parameters ?? { type: 'object', properties: {} },\n      responseFormat: responseFormat ?? 'content_and_artifact',\n    }\n  );\n}\n\n/**\n * Creates schema-only tools for all definitions in an array.\n */\nexport function createSchemaOnlyTools(\n  definitions: LCTool[]\n): StructuredToolInterface[] {\n  return definitions.map((def) => createSchemaOnlyTool(def));\n}\n"],"names":[],"mappings":";;AAGA;;;;AAIG;AACG,SAAU,oBAAoB,CAClC,UAAkB,EAAA;IAElB,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,UAAU;AAEpE,IAAA,OAAO,IAAI,CACT,YAAW;AACT,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,MAAA,EAAS,IAAI,CAAyD,uDAAA,CAAA;AACpE,YAAA,0DAA0D,CAC7D;AACH,KAAC,EACD;QACE,IAAI;QACJ,WAAW,EAAE,WAAW,IAAI,EAAE;QAC9B,MAAM,EAAE,UAAU,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QACxD,cAAc,EAAE,cAAc,IAAI,sBAAsB;AACzD,KAAA,CACF;AACH;AAEA;;AAEG;AACG,SAAU,qBAAqB,CACnC,WAAqB,EAAA;AAErB,IAAA,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,oBAAoB,CAAC,GAAG,CAAC,CAAC;AAC5D;;;;"}

package/dist/types/agents/AgentContext.d.ts

@@ -45,6 +45,11 @@ export declare class AgentContext {
      * Used for tool search and programmatic tool calling.
      */
     toolRegistry?: t.LCToolRegistry;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode.
+     */
+    toolDefinitions?: t.LCTool[];
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames: Set<string>;
     /** Instructions for this agent */
@@ -81,7 +86,7 @@ export declare class AgentContext {
         /** Names of sibling agents executing in parallel (empty if sequential) */
         parallelSiblings: string[];
     };
-    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         name?: string;
         provider: Providers;
@@ -92,6 +97,7 @@ export declare class AgentContext {
         tools?: t.GraphTools;
         toolMap?: t.ToolMap;
         toolRegistry?: t.LCToolRegistry;
+        toolDefinitions?: t.LCTool[];
         instructions?: string;
         additionalInstructions?: string;
         reasoningKey?: 'reasoning_content' | 'reasoning';

package/dist/types/common/enum.d.ts

@@ -17,6 +17,8 @@ export declare enum GraphEvents {
     ON_MESSAGE_DELTA = "on_message_delta",
     /** [Custom] Reasoning Delta events for messages */
     ON_REASONING_DELTA = "on_reasoning_delta",
+    /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+    ON_TOOL_EXECUTE = "on_tool_execute",
     /** Custom event, emitted by system */
     ON_CUSTOM_EVENT = "on_custom_event",
     /** Emitted when a chat model starts processing. */

package/dist/types/index.d.ts

@@ -8,6 +8,8 @@ export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
+export * from './tools/ToolNode';
+export * from './tools/createSchemaOnlyTool';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';

package/dist/types/tools/ToolNode.d.ts

@@ -18,7 +18,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private programmaticCache?;
     /** Reference to Graph's sessions map for automatic session injection */
     private sessions?;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, }: t.ToolNodeConstructorParams);
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    private eventDrivenMode;
+    /** Tool definitions for event-driven mode */
+    private toolDefinitions?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, toolDefinitions, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -33,6 +37,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * Runs a single tool call with error handling
      */
     protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    /**
+     * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+     * Used in event-driven mode where the host handles actual tool execution.
+     */
+    private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;
     private isSendInput;
     private isMessagesState;

package/dist/types/tools/createSchemaOnlyTool.d.ts

@@ -0,0 +1,12 @@
+import { type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export declare function createSchemaOnlyTool(definition: LCTool): StructuredToolInterface;
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export declare function createSchemaOnlyTools(definitions: LCTool[]): StructuredToolInterface[];

package/dist/types/types/graph.d.ts

@@ -256,4 +256,10 @@ export interface AgentInputs {
      * Maps tool name to LCTool definition.
      */
     toolRegistry?: Map<string, LCTool>;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode, dispatching
+     * ON_TOOL_EXECUTE events instead of invoking tools directly.
+     */
+    toolDefinitions?: LCTool[];
 }

package/dist/types/types/tools.d.ts

@@ -31,6 +31,10 @@ export type ToolNodeOptions = {
     toolRegistry?: LCToolRegistry;
     /** Reference to Graph's sessions map for automatic session injection */
     sessions?: ToolSessionMap;
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    eventDrivenMode?: boolean;
+    /** Tool definitions for event-driven mode (used for context, not invocation) */
+    toolDefinitions?: Map<string, LCTool>;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -96,6 +100,51 @@ export type LCTool = {
      * Options: 'direct', 'code_execution'
      */
     allowed_callers?: AllowedCaller[];
+    /** Response format for the tool output */
+    responseFormat?: 'content' | 'content_and_artifact';
+    /** Server name for MCP tools */
+    serverName?: string;
+    /** Tool type classification */
+    toolType?: 'builtin' | 'mcp' | 'action';
+};
+/** Single tool call within a batch request for event-driven execution */
+export type ToolCallRequest = {
+    /** Tool call ID from the LLM */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Step ID for tracking */
+    stepId?: string;
+    /** Usage turn count for this tool */
+    turn?: number;
+};
+/** Batch request containing ALL tool calls for a graph step */
+export type ToolExecuteBatchRequest = {
+    /** All tool calls from the AIMessage */
+    toolCalls: ToolCallRequest[];
+    /** User ID for context */
+    userId?: string;
+    /** Agent ID for context */
+    agentId?: string;
+    /** Promise resolver - handler calls this with ALL results */
+    resolve: (results: ToolExecuteResult[]) => void;
+    /** Promise rejector - handler calls this on fatal error */
+    reject: (error: Error) => void;
+};
+/** Result for a single tool call in event-driven execution */
+export type ToolExecuteResult = {
+    /** Matches ToolCallRequest.id */
+    toolCallId: string;
+    /** Tool output content */
+    content: string | unknown[];
+    /** Optional artifact (for content_and_artifact format) */
+    artifact?: unknown;
+    /** Execution status */
+    status: 'success' | 'error';
+    /** Error message if status is 'error' */
+    errorMessage?: string;
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.01",
+  "version": "3.1.21",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -34,6 +34,7 @@ export class AgentContext {
       toolMap,
       toolEnd,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additional_instructions,
       streamBuffer,
@@ -52,6 +53,7 @@ export class AgentContext {
       tools,
       toolMap,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additionalInstructions: additional_instructions,
       reasoningKey,
@@ -118,6 +120,11 @@ export class AgentContext {
    * Used for tool search and programmatic tool calling.
    */
   toolRegistry?: t.LCToolRegistry;
+  /**
+   * Serializable tool definitions for event-driven execution.
+   * When provided, ToolNode operates in event-driven mode.
+   */
+  toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
   /** Instructions for this agent */
@@ -171,6 +178,7 @@ export class AgentContext {
     tools,
     toolMap,
     toolRegistry,
+    toolDefinitions,
     instructions,
     additionalInstructions,
     reasoningKey,
@@ -188,6 +196,7 @@ export class AgentContext {
     tools?: t.GraphTools;
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
+    toolDefinitions?: t.LCTool[];
     instructions?: string;
     additionalInstructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -205,6 +214,7 @@ export class AgentContext {
     this.tools = tools;
     this.toolMap = toolMap;
     this.toolRegistry = toolRegistry;
+    this.toolDefinitions = toolDefinitions;
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
     if (reasoningKey) {

package/src/common/enum.ts

@@ -19,6 +19,8 @@ export enum GraphEvents {
   ON_MESSAGE_DELTA = 'on_message_delta',
   /** [Custom] Reasoning Delta events for messages */
   ON_REASONING_DELTA = 'on_reasoning_delta',
+  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+  ON_TOOL_EXECUTE = 'on_tool_execute',
 
   /* Official Events */
 

package/src/graphs/Graph.ts

@@ -58,6 +58,7 @@ import {
 } from '@/utils';
 import { getChatModelClass, manualToolStreamProviders } from '@/llm/providers';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { createSchemaOnlyTools } from '@/tools/createSchemaOnlyTool';
 import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { AgentContext } from '@/agents/AgentContext';
@@ -453,6 +454,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     currentToolMap?: t.ToolMap;
     agentContext?: AgentContext;
   }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
+    const toolDefinitions = agentContext?.toolDefinitions;
+    const eventDrivenMode =
+      toolDefinitions != null && toolDefinitions.length > 0;
+
+    if (eventDrivenMode) {
+      const schemaTools = createSchemaOnlyTools(toolDefinitions);
+      const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
+
+      return new CustomToolNode<t.BaseGraphState>({
+        tools: schemaTools as t.GenericTool[],
+        toolMap: new Map(schemaTools.map((tool) => [tool.name, tool])),
+        toolCallStepIds: this.toolCallStepIds,
+        errorHandler: (data, metadata) =>
+          StandardGraph.handleToolCallErrorStatic(this, data, metadata),
+        toolRegistry: agentContext?.toolRegistry,
+        sessions: this.sessions,
+        eventDrivenMode: true,
+        toolDefinitions: toolDefMap,
+      });
+    }
+
     return new CustomToolNode<t.BaseGraphState>({
       tools: (currentTools as t.GenericTool[] | undefined) ?? [],
       toolMap: currentToolMap,

package/src/index.ts

@@ -13,6 +13,8 @@ export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
+export * from './tools/ToolNode';
+export * from './tools/createSchemaOnlyTool';
 export * from './tools/handlers';
 export * from './tools/search';