@librechat/agents 3.0.0-rc1 → 3.0.0-rc10

package/src/scripts/test-multi-agent-list-handoff.ts

@@ -0,0 +1,261 @@
+#!/usr/bin/env bun
+
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import { Run } from '@/run';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import type * as t from '@/types';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Test supervisor-based multi-agent system using a single edge with multiple destinations
+ *
+ * Instead of creating 5 separate edges, we use one edge with an array of destinations
+ * This should create handoff tools for all 5 specialists from a single edge definition
+ */
+async function testSupervisorListHandoff() {
+  console.log('Testing Supervisor with List-Based Handoff Edge...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Track which specialist role was selected
+  let selectedRole = '';
+
+  // Create custom handlers
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        const runStepData = data as any;
+        if (runStepData?.name) {
+          console.log(`\n[${runStepData.name}] Processing...`);
+        }
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        const toolData = data as any;
+        if (toolData?.name?.startsWith(Constants.LC_TRANSFER_TO_)) {
+          const specialist = toolData.name.replace(
+            Constants.LC_TRANSFER_TO_,
+            ''
+          );
+          console.log(`\n🔀 Transferring to ${specialist}...`);
+          selectedRole = specialist;
+        }
+      },
+    },
+  };
+
+  // Function to create the graph with a single edge to multiple specialists
+  function createSupervisorGraphWithListEdge(): t.RunConfig {
+    console.log(`\nCreating graph with supervisor and 5 specialist agents.`);
+    console.log(
+      'Using a SINGLE edge with multiple destinations (list-based handoff).\n'
+    );
+
+    // Define the adaptive specialist configuration that will be reused
+    const specialistConfig = {
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are an Adaptive Specialist. Your agent ID indicates your role:
+      
+      - data_analyst: Focus on statistical analysis, metrics, ML evaluation, A/B testing
+      - security_expert: Focus on cybersecurity, vulnerability assessment, compliance  
+      - product_designer: Focus on UX/UI design, user research, accessibility
+      - devops_engineer: Focus on CI/CD, infrastructure, cloud platforms, monitoring
+      - legal_advisor: Focus on licensing, privacy laws, contracts, regulatory compliance
+      
+      The supervisor will provide specific instructions. Follow them while maintaining your expert perspective.`,
+      maxContextTokens: 8000,
+    };
+
+    // Create the graph with supervisor and all 5 specialists
+    const agents: t.AgentInputs[] = [
+      {
+        agentId: 'supervisor',
+        provider: Providers.ANTHROPIC,
+        clientOptions: {
+          modelName: 'claude-3-5-sonnet-latest',
+          apiKey: process.env.ANTHROPIC_API_KEY,
+        },
+        instructions: `You are a Task Supervisor with access to 5 specialist agents:
+        1. transfer_to_data_analyst - For statistical analysis and metrics
+        2. transfer_to_security_expert - For cybersecurity and vulnerability assessment  
+        3. transfer_to_product_designer - For UX/UI design
+        4. transfer_to_devops_engineer - For infrastructure and deployment
+        5. transfer_to_legal_advisor - For compliance and licensing
+        
+        Your role is to:
+        1. Analyze the incoming request
+        2. Decide which specialist is best suited
+        3. Use the appropriate transfer tool (e.g., transfer_to_data_analyst)
+        4. Provide specific instructions to guide their work
+        
+        Be specific about what you need from the specialist.`,
+        maxContextTokens: 8000,
+      },
+      // Include all 5 specialists with the same adaptive configuration
+      {
+        agentId: 'data_analyst',
+        ...specialistConfig,
+      },
+      {
+        agentId: 'security_expert',
+        ...specialistConfig,
+      },
+      {
+        agentId: 'product_designer',
+        ...specialistConfig,
+      },
+      {
+        agentId: 'devops_engineer',
+        ...specialistConfig,
+      },
+      {
+        agentId: 'legal_advisor',
+        ...specialistConfig,
+      },
+    ];
+
+    // Create a SINGLE edge from supervisor to ALL 5 specialists using a list
+    const edges: t.GraphEdge[] = [
+      {
+        from: 'supervisor',
+        to: [
+          'data_analyst',
+          'security_expert',
+          'product_designer',
+          'devops_engineer',
+          'legal_advisor',
+        ],
+        description:
+          'Transfer to appropriate specialist based on task requirements',
+        edgeType: 'handoff',
+      },
+    ];
+
+    return {
+      runId: `supervisor-list-handoff-${Date.now()}`,
+      graphConfig: {
+        type: 'multi-agent',
+        agents,
+        edges,
+      },
+      customHandlers,
+      returnContent: true,
+    };
+  }
+
+  try {
+    // Test with different queries
+    const testQueries = [
+      // 'How can we analyze user engagement metrics to improve our product?',
+      // 'What security measures should we implement for our new API?',
+      // 'Can you help design a better onboarding flow for our mobile app?',
+      // 'We need to set up a CI/CD pipeline for our microservices.',
+      'What are the legal implications of using GPL-licensed code in our product?',
+    ];
+
+    const config = {
+      configurable: {
+        thread_id: 'supervisor-list-handoff-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    for (const query of testQueries) {
+      console.log(`\n${'='.repeat(60)}`);
+      console.log(`USER QUERY: "${query}"`);
+      console.log('='.repeat(60));
+
+      // Reset conversation
+      conversationHistory.length = 0;
+      conversationHistory.push(new HumanMessage(query));
+
+      // Create graph with supervisor having a single edge to multiple specialists
+      const runConfig = createSupervisorGraphWithListEdge();
+      const run = await Run.create(runConfig);
+
+      console.log('Processing request...');
+
+      // Process with streaming
+      const inputs = {
+        messages: conversationHistory,
+      };
+
+      const finalContentParts = await run.processStream(inputs, config);
+      const finalMessages = run.getRunMessages();
+
+      if (finalMessages) {
+        conversationHistory.push(...finalMessages);
+      }
+
+      // Show summary
+      console.log(`\n${'─'.repeat(60)}`);
+      console.log(`Graph structure:`);
+      console.log(`- Agents: 6 total (supervisor + 5 specialists)`);
+      console.log(`- Edges: 1 edge with multiple destinations`);
+      console.log(
+        `- Edge type: handoff (creates individual tools for each destination)`
+      );
+      console.log(
+        `- Result: Supervisor has 5 handoff tools from a single edge`
+      );
+      console.log('─'.repeat(60));
+    }
+
+    // Final summary
+    console.log(`\n${'='.repeat(60)}`);
+    console.log('TEST COMPLETE');
+    console.log('='.repeat(60));
+    console.log('\nThis test demonstrates that a single edge with multiple');
+    console.log('destinations in the "to" field creates individual handoff');
+    console.log('tools for each destination agent, achieving the same result');
+    console.log('as creating separate edges for each specialist.');
+  } catch (error) {
+    console.error('Error in supervisor list handoff test:', error);
+  }
+}
+
+// Run the test
+testSupervisorListHandoff();

package/src/scripts/test-tools-before-handoff.ts

@@ -0,0 +1,233 @@
+import { config } from 'dotenv';
+config();
+
+import { TavilySearch } from '@langchain/tavily';
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import { Run } from '@/run';
+import { Providers, GraphEvents } from '@/common';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import type * as t from '@/types';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Test edge case: Agent performs 2 web searches before handing off
+ *
+ * This tests how the system behaves when an agent with handoff capabilities
+ * uses tools before transferring control to another agent.
+ */
+async function testToolsBeforeHandoff() {
+  console.log('Testing Tools Before Handoff Edge Case...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Track tool calls and handoffs
+  let toolCallCount = 0;
+  let handoffOccurred = false;
+
+  // Create custom handlers
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(undefined, (name?: string) => {
+      console.log(`\n✅ Tool completed: ${name}`);
+      return true;
+    }),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        const runStepData = data as any;
+        if (runStepData?.name) {
+          console.log(`\n[${runStepData.name}] Processing...`);
+        }
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        // console.log('====== ON_MESSAGE_DELTA ======');
+        console.dir(data, { depth: null });
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        const toolData = data as any;
+        console.log(`\n🔧 Tool started:`);
+        console.dir({ toolData, metadata }, { depth: null });
+
+        if (toolData?.output?.name === 'tavily_search_results_json') {
+          toolCallCount++;
+          console.log(`📊 Search #${toolCallCount} initiated`);
+        } else if (toolData?.output?.name?.includes('transfer_to_')) {
+          handoffOccurred = true;
+          const specialist = toolData.name.replace('transfer_to_', '');
+          console.log(`\n🔀 Handoff initiated to: ${specialist}`);
+        }
+      },
+    },
+  };
+
+  // Create the graph with research agent and report writer
+  function createGraphWithToolsAndHandoff(): t.RunConfig {
+    const agents: t.AgentInputs[] = [
+      {
+        agentId: 'research_coordinator',
+        provider: Providers.OPENAI,
+        clientOptions: {
+          modelName: 'gpt-4.1-mini',
+          apiKey: process.env.OPENAI_API_KEY,
+        },
+        tools: [new TavilySearch({ maxResults: 3 })],
+        instructions: `You are a Research Coordinator with access to web search and a report writer specialist.
+        
+        Your workflow MUST follow these steps IN ORDER:
+        1. FIRST: Write an initial response acknowledging the request and outlining your research plan
+           - Explain what aspects you'll investigate
+           - Describe your search strategy
+        2. SECOND: Conduct exactly 2 web searches to gather comprehensive information
+           - Search 1: Get general information about the topic
+           - Search 2: Get specific details, recent updates, or complementary data
+           - Note: Even if your searches are unsuccessful, you MUST still proceed to handoff after EXACTLY 2 searches
+        3. FINALLY: After completing both searches, transfer to the report writer
+           - Provide the report writer with a summary of your findings
+        
+        CRITICAL: You MUST write your initial response before ANY tool use. Then complete both searches before handoff.`,
+        maxContextTokens: 8000,
+      },
+      {
+        agentId: 'report_writer',
+        provider: Providers.OPENAI,
+        clientOptions: {
+          modelName: 'gpt-5-mini',
+          apiKey: process.env.OPENAI_API_KEY,
+        },
+        instructions: `You are a Report Writer specialist. Your role is to:
+        1. Receive research findings from the Research Coordinator
+        2. Create a well-structured, comprehensive report
+        3. Include all key findings from the research
+        4. Format the report with clear sections and bullet points
+        5. Add a brief executive summary at the beginning
+        
+        Focus on clarity, completeness, and professional presentation.`,
+        maxContextTokens: 8000,
+      },
+    ];
+
+    // Create edge from research coordinator to report writer
+    const edges: t.GraphEdge[] = [
+      {
+        from: 'research_coordinator',
+        to: 'report_writer',
+        description: 'Transfer to report writer after completing research',
+        edgeType: 'handoff',
+      },
+    ];
+
+    return {
+      runId: `tools-before-handoff-${Date.now()}`,
+      graphConfig: {
+        type: 'multi-agent',
+        agents,
+        edges,
+      },
+      customHandlers,
+      returnContent: true,
+    };
+  }
+
+  try {
+    // Single test query that requires research before report writing
+    const query = `Research the latest developments in quantum computing from 2025, 
+    including major breakthroughs and commercial applications. 
+    I need a comprehensive report with recent findings.`;
+
+    console.log('='.repeat(60));
+    console.log(`USER QUERY: "${query}"`);
+    console.log('='.repeat(60));
+
+    // Create the graph
+    const runConfig = createGraphWithToolsAndHandoff();
+    const run = await Run.create(runConfig);
+
+    console.log('\nExpected behavior:');
+    console.log('1. Research Coordinator writes initial response/plan');
+    console.log('2. Research Coordinator performs 2 web searches');
+    console.log('3. Research Coordinator hands off to Report Writer');
+    console.log('4. Report Writer creates final report\n');
+
+    // Process with streaming
+    conversationHistory.push(new HumanMessage(query));
+    const inputs = {
+      messages: conversationHistory,
+    };
+
+    const config = {
+      configurable: {
+        thread_id: 'tools-handoff-test-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    const finalContentParts = await run.processStream(inputs, config);
+    const finalMessages = run.getRunMessages();
+
+    if (finalMessages) {
+      conversationHistory.push(...finalMessages);
+    }
+
+    // Show results summary
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log('EDGE CASE TEST RESULTS:');
+    console.log('─'.repeat(60));
+    console.log(`Tool calls before handoff: ${toolCallCount}`);
+    console.log(`Expected tool calls: 2`);
+    console.log(`Handoff occurred: ${handoffOccurred ? 'Yes ✅' : 'No ❌'}`);
+    console.log(
+      `Test status: ${toolCallCount === 2 && handoffOccurred ? 'PASSED ✅' : 'FAILED ❌'}`
+    );
+    console.log('─'.repeat(60));
+
+    // Display conversation history
+    console.log('\nConversation History:');
+    console.log('─'.repeat(60));
+    conversationHistory.forEach((msg, idx) => {
+      const role = msg.constructor.name.replace('Message', '');
+      console.log(`\n[${idx}] ${role}:`);
+      if (typeof msg.content === 'string') {
+        console.log(
+          msg.content.substring(0, 200) +
+            (msg.content.length > 200 ? '...' : '')
+        );
+      }
+    });
+  } catch (error) {
+    console.error('Error in tools-before-handoff test:', error);
+  }
+}
+
+// Run the test
+testToolsBeforeHandoff();

package/src/stream.ts

@@ -153,7 +153,10 @@ export class ChatModelStreamHandler implements t.EventHandler {
     if (
       chunk.tool_calls &&
       chunk.tool_calls.length > 0 &&
-      chunk.tool_calls.every((tc) => tc.id != null && tc.id !== '')
+      chunk.tool_calls.every(
+        (tc) =>
+          tc.id != null && tc.id !== '' && tc.name != null && tc.name !== ''
+      )
     ) {
       hasToolCalls = true;
       await handleToolCalls(chunk.tool_calls, metadata, graph);

package/src/types/graph.ts

@@ -66,6 +66,10 @@ export type BaseGraphState = {
   messages: BaseMessage[];
 };
 
+export type MultiAgentGraphState = BaseGraphState & {
+  agentMessages?: BaseMessage[];
+};
+
 export type IState = BaseGraphState;
 
 export interface EventHandler {
@@ -116,6 +120,27 @@ export type CompiledStateWorkflow = CompiledStateGraph<
   StateDefinition
 >;
 
+export type CompiledMultiAgentWorkflow = CompiledStateGraph<
+  StateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+  }>,
+  UpdateType<{
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+  }>,
+  string,
+  {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+  },
+  {
+    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;
+  },
+  StateDefinition
+>;
+
 export type CompiledAgentWorfklow = CompiledStateGraph<
   {
     messages: BaseMessage[];
@@ -290,19 +315,40 @@ export type StandardGraphInput = {
 };
 
 export type GraphEdge = {
-  /** Use a list for multiple sources */
+  /** Agent ID, use a list for multiple sources */
   from: string | string[];
-  /** Use a list for multiple destinations */
+  /** Agent ID, use a list for multiple destinations */
   to: string | string[];
   description?: string;
   /** Can return boolean or specific destination(s) */
   condition?: (state: BaseGraphState) => boolean | string | string[];
   /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
   edgeType?: 'handoff' | 'direct';
-  /** Optional prompt to add when transitioning through this edge */
-  promptInstructions?:
+  /**
+   * For direct edges: Optional prompt to add when transitioning through this edge.
+   * String prompts can include variables like {results} which will be replaced with
+   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.
+   *
+   * For handoff edges: Description for the input parameter that the handoff tool accepts,
+   * allowing the supervisor to pass specific instructions/context to the transferred agent.
+   */
+  prompt?:
     | string
-    | ((messages: BaseMessage[]) => string | undefined);
+    | ((
+        messages: BaseMessage[],
+        runStartIndex: number
+      ) => string | Promise<string> | undefined);
+  /**
+   * When true, excludes messages from startIndex when adding prompt.
+   * Automatically set to true when {results} variable is used in prompt.
+   */
+  excludeResults?: boolean;
+  /**
+   * For handoff edges: Customizes the parameter name for the handoff input.
+   * Defaults to "instructions" if not specified.
+   * Only applies when prompt is provided for handoff edges.
+   */
+  promptKey?: string;
 };
 
 export type MultiAgentGraphInput = StandardGraphInput & {

package/src/types/llm.ts

@@ -93,6 +93,7 @@ export type ClientOptions =
 
 export type SharedLLMConfig = {
   provider: Providers;
+  _lc_stream_delay?: number;
 };
 
 export type LLMConfig = SharedLLMConfig &

package/src/types/run.ts

@@ -103,9 +103,14 @@ export type MultiAgentGraphConfig = {
   edges: g.GraphEdge[];
 };
 
+export type StandardGraphConfig = Omit<
+  MultiAgentGraphConfig,
+  'edges' | 'type'
+> & { type?: 'standard'; signal?: AbortSignal };
+
 export type RunConfig = {
   runId: string;
-  graphConfig: LegacyGraphConfig | MultiAgentGraphConfig;
+  graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
   customHandlers?: Record<string, g.EventHandler>;
   returnContent?: boolean;
   tokenCounter?: TokenCounter;

package/dist/types/scripts/abort.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/ant_web_search.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/args.d.ts

@@ -1,7 +0,0 @@
-import { Providers } from '@/common';
-export declare function getArgs(): Promise<{
-    userName: string;
-    location: string;
-    provider: Providers;
-    currentDate: string;
-}>;

package/dist/types/scripts/caching.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/cli.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/cli2.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/cli3.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/cli4.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/cli5.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/code_exec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/code_exec_files.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/code_exec_simple.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/content.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/empty_input.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/handoff-test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/image.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/memory.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/multi-agent-conditional.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/scripts/multi-agent-parallel.d.ts

@@ -1 +0,0 @@
-export {};