@librechat/agents 3.0.35 → 3.0.40

package/src/scripts/programmatic_exec_agent.ts

@@ -0,0 +1,231 @@
+// src/scripts/programmatic_exec_agent.ts
+/**
+ * Test script for Programmatic Tool Calling (PTC) with agent integration.
+ * Run with: npm run programmatic_exec_agent
+ *
+ * Demonstrates:
+ * 1. Tool classification with allowed_callers:
+ *    - direct: Tool bound to LLM (can be called directly)
+ *    - code_execution: Tool available for PTC (not bound to LLM)
+ *    - Both: Tool bound to LLM AND available for PTC
+ * 2. Deferred loading with defer_loading: true (for tool search)
+ * 3. Agent-level tool configuration via toolRegistry
+ * 4. ToolNode runtime injection of programmatic tools
+ *
+ * This shows the real-world integration pattern with agents.
+ */
+import { config } from 'dotenv';
+config();
+
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { createCodeExecutionTool } from '@/tools/CodeExecutor';
+import { createProgrammaticToolCallingTool } from '@/tools/ProgrammaticToolCalling';
+import { createToolSearchRegexTool } from '@/tools/ToolSearchRegex';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { Run } from '@/run';
+import {
+  createGetTeamMembersTool,
+  createGetExpensesTool,
+  createGetWeatherTool,
+  createProgrammaticToolRegistry,
+} from '@/test/mockTools';
+
+// ============================================================================
+// Tool Registry (Metadata)
+// ============================================================================
+
+/**
+ * Tool registry only needs business logic tools that require filtering.
+ * Special tools (execute_code, programmatic_code_execution, tool_search_regex)
+ * are always bound directly to the LLM and don't need registry entries.
+ */
+function createAgentToolRegistry(): t.LCToolRegistry {
+  // Use shared programmatic tool registry (get_team_members, get_expenses, etc.)
+  return createProgrammaticToolRegistry();
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+const conversationHistory: BaseMessage[] = [];
+
+async function main(): Promise<void> {
+  console.log('Programmatic Tool Calling - Agent Integration Test');
+  console.log('===================================================\n');
+
+  const { userName, location, provider } = await getArgs();
+  const llmConfig = getLLMConfig(provider);
+
+  // Create all tool instances
+  const mockTools: StructuredToolInterface[] = [
+    createGetTeamMembersTool(),
+    createGetExpensesTool(),
+    createGetWeatherTool(),
+  ];
+
+  const toolMap = new Map(mockTools.map((t) => [t.name, t]));
+
+  // Create special tools (PTC, code execution, tool search)
+  const codeExecTool = createCodeExecutionTool();
+  const ptcTool = createProgrammaticToolCallingTool();
+  const toolSearchTool = createToolSearchRegexTool();
+
+  // Build complete tool list and map
+  const allTools = [...mockTools, codeExecTool, ptcTool, toolSearchTool];
+  const completeToolMap = new Map(allTools.map((t) => [t.name, t]));
+
+  // Create tool registry with allowed_callers configuration
+  // Only includes business logic tools (not special tools like execute_code, PTC, tool_search)
+  const toolRegistry = createAgentToolRegistry();
+
+  console.log('Tool configuration:');
+  console.log('- Total tools:', allTools.length);
+  console.log(
+    '- Programmatic-allowed:',
+    Array.from(toolRegistry.values())
+      .filter((t) => t.allowed_callers?.includes('code_execution'))
+      .map((t) => t.name)
+      .join(', ')
+  );
+  console.log(
+    '- Direct-only:',
+    Array.from(toolRegistry.values())
+      .filter(
+        (t) =>
+          !t.allowed_callers ||
+          (t.allowed_callers.includes('direct') &&
+            !t.allowed_callers.includes('code_execution'))
+      )
+      .map((t) => t.name)
+      .join(', ')
+  );
+  console.log(
+    '- Both:',
+    Array.from(toolRegistry.values())
+      .filter(
+        (t) =>
+          t.allowed_callers?.includes('direct') &&
+          t.allowed_callers?.includes('code_execution')
+      )
+      .map((t) => t.name)
+      .join(', ')
+  );
+
+  // Create run with toolRegistry configuration
+  const run = await Run.create<t.IState>({
+    runId: 'ptc-agent-test',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      agents: [
+        {
+          agentId: 'default',
+          provider: llmConfig.provider,
+          clientOptions: llmConfig,
+          tools: allTools,
+          toolMap: completeToolMap,
+          toolRegistry, // Pass tool registry for programmatic/deferred tool config
+          instructions:
+            'You are an AI assistant with access to programmatic tool calling. ' +
+            'When you need to process multiple items or perform complex data operations, ' +
+            'use the programmatic_code_execution tool to write Python code that calls tools efficiently.',
+        },
+      ],
+    },
+    returnContent: true,
+  });
+
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    streamMode: string;
+  } = {
+    configurable: {
+      provider,
+      thread_id: 'ptc-test-conversation',
+    },
+    streamMode: 'values',
+    version: 'v2',
+  };
+
+  console.log('\n' + '='.repeat(70));
+  console.log('Test: Process team expenses using PTC');
+  console.log('='.repeat(70) + '\n');
+
+  const userMessage = new HumanMessage(
+    `Hi! I need you to analyze our team's expenses. Please:
+1. Get the list of team members
+2. For each member, get their expense records
+3. Calculate the total expenses per member
+4. Identify anyone who spent more than $300
+5. Show me the results in a nice format
+
+Use the programmatic_code_execution tool to do this efficiently - don't call each tool separately!`
+  );
+
+  conversationHistory.push(userMessage);
+
+  const inputs = {
+    messages: conversationHistory,
+  };
+
+  console.log('Running agent with PTC capability...\n');
+
+  const finalContentParts = await run.processStream(inputs, config);
+  const finalMessages = run.getRunMessages();
+
+  if (finalMessages) {
+    conversationHistory.push(...finalMessages);
+  }
+
+  console.log('\n' + '='.repeat(70));
+  console.log('Agent Response:');
+  console.log('='.repeat(70));
+
+  if (finalContentParts) {
+    for (const part of finalContentParts) {
+      if (part?.type === 'text' && part.text) {
+        console.log(part.text);
+      }
+    }
+  }
+
+  console.log('\n' + '='.repeat(70));
+  console.log('Test completed successfully!');
+  console.log('='.repeat(70));
+  console.log('\nKey observations:');
+  console.log(
+    '1. LLM only sees tools with allowed_callers including "direct" (get_weather, execute_code, programmatic_code_execution, tool_search_regex)'
+  );
+  console.log(
+    '2. When PTC is invoked, ToolNode automatically injects programmatic tools (get_team_members, get_expenses, get_weather)'
+  );
+  console.log(
+    '3. No need to manually configure runtime toolMap - handled by agent context'
+  );
+  console.log(
+    '4. Tool filtering based on allowed_callers happens automatically\n'
+  );
+}
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  console.log('Conversation history:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});
+
+process.on('uncaughtException', (err) => {
+  console.error('Uncaught Exception:', err);
+});
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  console.log('Conversation history:');
+  console.dir(conversationHistory, { depth: null });
+  process.exit(1);
+});

package/src/scripts/tool_search_regex.ts

@@ -0,0 +1,162 @@
+// src/scripts/tool_search_regex.ts
+/**
+ * Test script for the Tool Search Regex tool.
+ * Run with: npm run tool_search_regex
+ *
+ * Demonstrates runtime registry injection - the tool registry is passed
+ * at invocation time, not at initialization time.
+ */
+import { config } from 'dotenv';
+config();
+
+import { createToolSearchRegexTool } from '@/tools/ToolSearchRegex';
+import type { LCToolRegistry } from '@/types';
+import { createToolSearchToolRegistry } from '@/test/mockTools';
+
+interface RunTestOptions {
+  fields?: ('name' | 'description' | 'parameters')[];
+  max_results?: number;
+  showArtifact?: boolean;
+  toolRegistry: LCToolRegistry;
+  onlyDeferred?: boolean;
+}
+
+async function runTest(
+  searchTool: ReturnType<typeof createToolSearchRegexTool>,
+  testName: string,
+  query: string,
+  options: RunTestOptions
+): Promise<void> {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`TEST: ${testName}`);
+  console.log(`Query: "${query}"`);
+  if (options.fields) console.log(`Fields: ${options.fields.join(', ')}`);
+  if (options.max_results) console.log(`Max Results: ${options.max_results}`);
+  console.log('='.repeat(60));
+
+  try {
+    const startTime = Date.now();
+
+    // Manual testing uses schema params directly
+    // (ToolNode uses different param structure when injecting)
+    const result = await searchTool.invoke({
+      query,
+      fields: options.fields,
+      max_results: options.max_results,
+    });
+    const duration = Date.now() - startTime;
+
+    console.log(`\nResult (${duration}ms):`);
+    if (Array.isArray(result)) {
+      console.log(result[0]);
+      if (options.showArtifact) {
+        console.log('\n--- Artifact ---');
+        console.dir(result[1], { depth: null });
+      }
+    } else {
+      console.log(result);
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : error);
+  }
+}
+
+async function main(): Promise<void> {
+  console.log('Tool Search Regex - Test Script');
+  console.log('================================');
+  console.log('Demonstrating runtime tool registry injection\n');
+
+  const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
+  if (!apiKey) {
+    console.error(
+      'Error: LIBRECHAT_CODE_API_KEY environment variable is not set.'
+    );
+    console.log('Please set it in your .env file or environment.');
+    process.exit(1);
+  }
+
+  console.log('Creating sample tool registry...');
+  const toolRegistry = createToolSearchToolRegistry();
+  console.log(
+    `Registry contains ${toolRegistry.size} tools (${Array.from(toolRegistry.values()).filter((t) => t.defer_loading).length} deferred)`
+  );
+
+  console.log('\nCreating Tool Search Regex tool WITH registry for testing...');
+  const searchTool = createToolSearchRegexTool({ apiKey, toolRegistry });
+  console.log('Tool created successfully!');
+  console.log(
+    'Note: In production, ToolNode injects toolRegistry via params when invoked through the graph.\n'
+  );
+
+  const baseOptions = { toolRegistry, onlyDeferred: true };
+
+  // Test 1: Simple keyword search (with artifact display)
+  await runTest(searchTool, 'Simple keyword search', 'expense', {
+    ...baseOptions,
+    showArtifact: true,
+  });
+
+  // Test 2: Search for weather-related tools
+  await runTest(searchTool, 'Weather tools', 'weather|forecast', baseOptions);
+
+  // Test 3: Search with case variations
+  await runTest(searchTool, 'Case insensitive search', 'EMAIL', baseOptions);
+
+  // Test 4: Search in description only
+  await runTest(searchTool, 'Description-only search', 'database', {
+    ...baseOptions,
+    fields: ['description'],
+  });
+
+  // Test 5: Search with parameters field
+  await runTest(searchTool, 'Parameters search', 'query', {
+    ...baseOptions,
+    fields: ['parameters'],
+  });
+
+  // Test 6: Limited results
+  await runTest(searchTool, 'Limited to 2 results', 'get', {
+    ...baseOptions,
+    max_results: 2,
+  });
+
+  // Test 7: Pattern that matches nothing
+  await runTest(searchTool, 'No matches', 'xyznonexistent123', baseOptions);
+
+  // Test 8: Regex pattern with character class
+  await runTest(
+    searchTool,
+    'Regex with character class',
+    'get_[a-z]+',
+    baseOptions
+  );
+
+  // Test 9: Dangerous pattern (should be sanitized)
+  await runTest(
+    searchTool,
+    'Dangerous pattern (sanitized)',
+    '(a+)+',
+    baseOptions
+  );
+
+  // Test 10: Search all fields
+  await runTest(searchTool, 'All fields search', 'text', {
+    ...baseOptions,
+    fields: ['name', 'description', 'parameters'],
+  });
+
+  // Test 11: Search ALL tools (not just deferred)
+  await runTest(searchTool, 'Search ALL tools (incl. non-deferred)', 'calc', {
+    toolRegistry,
+    onlyDeferred: false, // Include non-deferred tools
+  });
+
+  console.log('\n' + '='.repeat(60));
+  console.log('All tests completed!');
+  console.log('='.repeat(60) + '\n');
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});