@librechat/agents 3.1.1 → 3.1.21

package/src/tools/createSchemaOnlyTool.ts

@@ -0,0 +1,37 @@
+import { tool, 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 function createSchemaOnlyTool(
+  definition: LCTool
+): StructuredToolInterface {
+  const { name, description, parameters, responseFormat } = definition;
+
+  return tool(
+    async () => {
+      throw new Error(
+        `Tool "${name}" should not be invoked directly in event-driven mode. ` +
+          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'
+      );
+    },
+    {
+      name,
+      description: description ?? '',
+      schema: parameters ?? { type: 'object', properties: {} },
+      responseFormat: responseFormat ?? 'content_and_artifact',
+    }
+  );
+}
+
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export function createSchemaOnlyTools(
+  definitions: LCTool[]
+): StructuredToolInterface[] {
+  return definitions.map((def) => createSchemaOnlyTool(def));
+}

package/src/types/graph.ts

@@ -377,4 +377,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/src/types/tools.ts

@@ -41,6 +41,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;
@@ -125,6 +129,54 @@ 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 */