@librechat/agents 2.4.321 → 3.0.0-rc1

package/src/scripts/handoff-test.ts

@@ -0,0 +1,135 @@
+import { config } from 'dotenv';
+config();
+
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import {
+  StateGraph,
+  MessagesAnnotation,
+  Command,
+  START,
+  getCurrentTaskInput,
+  END,
+} from '@langchain/langgraph';
+import { ToolMessage } from '@langchain/core/messages';
+
+interface CreateHandoffToolParams {
+  agentName: string;
+  description?: string;
+}
+
+const createHandoffTool = ({
+  agentName,
+  description,
+}: CreateHandoffToolParams) => {
+  const toolName = `transfer_to_${agentName}`;
+  const toolDescription = description || `Ask agent '${agentName}' for help`;
+
+  const handoffTool = tool(
+    async (_, config) => {
+      const toolMessage = new ToolMessage({
+        content: `Successfully transferred to ${agentName}`,
+        name: toolName,
+        tool_call_id: config.toolCall.id,
+      });
+
+      // inject the current agent state
+      const state =
+        getCurrentTaskInput() as (typeof MessagesAnnotation)['State'];
+      return new Command({
+        goto: agentName,
+        update: { messages: state.messages.concat(toolMessage) },
+        graph: Command.PARENT,
+      });
+    },
+    {
+      name: toolName,
+      schema: z.object({}),
+      description: toolDescription,
+    }
+  );
+
+  return handoffTool;
+};
+
+const bookHotel = tool(
+  async (input: { hotel_name: string }) => {
+    return `Successfully booked a stay at ${input.hotel_name}.`;
+  },
+  {
+    name: 'book_hotel',
+    description: 'Book a hotel',
+    schema: z.object({
+      hotel_name: z.string().describe('The name of the hotel to book'),
+    }),
+  }
+);
+
+const bookFlight = tool(
+  async (input: { from_airport: string; to_airport: string }) => {
+    return `Successfully booked a flight from ${input.from_airport} to ${input.to_airport}.`;
+  },
+  {
+    name: 'book_flight',
+    description: 'Book a flight',
+    schema: z.object({
+      from_airport: z.string().describe('The departure airport code'),
+      to_airport: z.string().describe('The arrival airport code'),
+    }),
+  }
+);
+
+const transferToHotelAssistant = createHandoffTool({
+  agentName: 'hotel_assistant',
+  description: 'Transfer user to the hotel-booking assistant.',
+});
+
+const transferToFlightAssistant = createHandoffTool({
+  agentName: 'flight_assistant',
+  description: 'Transfer user to the flight-booking assistant.',
+});
+
+const llm = new ChatAnthropic({
+  modelName: 'claude-3-5-sonnet-latest',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const flightAssistant = createReactAgent({
+  llm,
+  tools: [bookFlight, transferToHotelAssistant],
+  prompt: 'You are a flight booking assistant',
+  name: 'flight_assistant',
+});
+
+const hotelAssistant = createReactAgent({
+  llm,
+  tools: [bookHotel, transferToFlightAssistant],
+  prompt: 'You are a hotel booking assistant',
+  name: 'hotel_assistant',
+});
+
+const multiAgentGraph = new StateGraph(MessagesAnnotation)
+  .addNode('flight_assistant', flightAssistant, {
+    ends: ['hotel_assistant', END],
+  })
+  .addNode('hotel_assistant', hotelAssistant, {
+    ends: ['flight_assistant', END],
+  })
+  .addEdge(START, 'flight_assistant')
+  .compile();
+
+const stream = await multiAgentGraph.stream({
+  messages: [
+    {
+      role: 'user',
+      content: 'book a flight from BOS to JFK and a stay at McKittrick Hotel',
+    },
+  ],
+});
+
+for await (const chunk of stream) {
+  console.log(chunk);
+  console.log('\n');
+}

package/src/scripts/image.ts

@@ -5,14 +5,17 @@ import { HumanMessage, AIMessage, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler, createMetadataAggregator } from '@/events';
+import {
+  ToolEndHandler,
+  ModelEndHandler,
+  createMetadataAggregator,
+} from '@/events';
 import { fetchRandomImageTool, fetchRandomImageURL } from '@/tools/example';
 import { getLLMConfig } from '@/utils/llmConfig';
 import { getArgs } from '@/scripts/args';
 import { GraphEvents } from '@/common';
 import { Run } from '@/run';
 
-
 const conversationHistory: BaseMessage[] = [];
 
 async function testCodeExecution(): Promise<void> {
@@ -23,38 +26,57 @@ async function testCodeExecution(): Promise<void> {
     [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-      handle: (event: GraphEvents.ON_RUN_STEP_COMPLETED, data: t.StreamEventData): void => {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
         console.log('====== ON_RUN_STEP_COMPLETED ======');
         console.dir(data, { depth: null });
-        aggregateContent({ event, data: data as unknown as { result: t.ToolEndEvent } });
-      }
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
     },
     [GraphEvents.ON_RUN_STEP]: {
-      handle: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData): void => {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
         console.log('====== ON_RUN_STEP ======');
         console.dir(data, { depth: null });
         aggregateContent({ event, data: data as t.RunStep });
-      }
+      },
     },
     [GraphEvents.ON_RUN_STEP_DELTA]: {
-      handle: (event: GraphEvents.ON_RUN_STEP_DELTA, data: t.StreamEventData): void => {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
         console.log('====== ON_RUN_STEP_DELTA ======');
         console.dir(data, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
-      }
+      },
     },
     [GraphEvents.ON_MESSAGE_DELTA]: {
-      handle: (event: GraphEvents.ON_MESSAGE_DELTA, data: t.StreamEventData): void => {
+      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 => {
+      handle: (
+        _event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
         console.log('====== TOOL_START ======');
         console.dir(data, { depth: null });
-      }
+      },
     },
   };
 
@@ -67,14 +89,19 @@ async function testCodeExecution(): Promise<void> {
       llmConfig,
       tools: [fetchRandomImageTool],
       // tools: [fetchRandomImageURL],
-      instructions: 'You are a friendly AI assistant with internet capabilities. Always address the user by their name.',
+      instructions:
+        'You are a friendly AI assistant with internet capabilities. Always address the user by their name.',
       additional_instructions: `The user's name is ${userName} and they are located in ${location}.`,
     },
     returnContent: true,
     customHandlers,
   });
 
-  const config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string; streamMode: string } = {
+  const config: Partial<RunnableConfig> & {
+    version: 'v1' | 'v2';
+    run_id?: string;
+    streamMode: string;
+  } = {
     configurable: {
       provider,
       thread_id: 'conversation-num-1',
@@ -109,7 +136,9 @@ async function testCodeExecution(): Promise<void> {
   inputs = {
     messages: conversationHistory,
   };
-  const finalContentParts2 = await run.processStream(inputs, config, { keepContent: true });
+  const finalContentParts2 = await run.processStream(inputs, config, {
+    keepContent: true,
+  });
   const finalMessages2 = run.getRunMessages();
   if (finalMessages2) {
     conversationHistory.push(...finalMessages2);
@@ -119,12 +148,15 @@ async function testCodeExecution(): Promise<void> {
 
   const { handleLLMEnd, collected } = createMetadataAggregator();
   const titleResult = await run.generateTitle({
+    provider,
     inputText: userMessage2,
     contentParts,
     chainOptions: {
-      callbacks: [{
-        handleLLMEnd,
-      }],
+      callbacks: [
+        {
+          handleLLMEnd,
+        },
+      ],
     },
   });
   console.log('Generated Title:', titleResult);
@@ -143,4 +175,4 @@ testCodeExecution().catch((err) => {
   console.log('Conversation history:');
   console.dir(conversationHistory, { depth: null });
   process.exit(1);
-});
+});

package/src/scripts/multi-agent-conditional.ts

@@ -0,0 +1,220 @@
+import { config } from 'dotenv';
+config();
+
+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[] = [];
+
+/**
+ * Example of conditional multi-agent system
+ *
+ * Graph structure:
+ * START -> classifier
+ * classifier -> technical_expert (if technical question)
+ * classifier -> business_expert (if business question)
+ * classifier -> general_assistant (otherwise)
+ * [all experts] -> END
+ */
+async function testConditionalMultiAgent() {
+  console.log('Testing Conditional Multi-Agent System...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Define specialized agents
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'classifier',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions:
+        'You are a query classifier. Analyze user questions and determine if they are technical, business-related, or general.',
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'technical_expert',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions:
+        'You are a technical expert. Provide detailed technical answers about programming, systems, and technology.',
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'business_expert',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions:
+        'You are a business expert. Provide insights on business strategy, operations, and management.',
+      maxContextTokens: 8000,
+    },
+    {
+      agentId: 'general_assistant',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-3-5-sonnet-latest',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions:
+        'You are a helpful general assistant. Answer questions on a wide range of topics.',
+      maxContextTokens: 8000,
+    },
+  ];
+
+  // Define conditional edges
+  // These create handoff tools with conditional routing logic
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'classifier',
+      to: ['technical_expert', 'business_expert', 'general_assistant'],
+      description: 'Route to appropriate expert based on query type',
+      condition: (state: t.BaseGraphState) => {
+        // Simple keyword-based routing for demo
+        // In a real system, this would use the classifier's analysis
+        const lastMessage = state.messages[state.messages.length - 1];
+        const content = lastMessage.content?.toString().toLowerCase() || '';
+
+        if (
+          content.includes('code') ||
+          content.includes('programming') ||
+          content.includes('technical')
+        ) {
+          return 'technical_expert';
+        } else if (
+          content.includes('business') ||
+          content.includes('strategy') ||
+          content.includes('market')
+        ) {
+          return 'business_expert';
+        } else {
+          return 'general_assistant';
+        }
+      },
+    },
+  ];
+
+  // Track selected expert
+  let selectedExpert = '';
+
+  // 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_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        const runStepData = data as any;
+        if (runStepData?.name && runStepData.name !== 'classifier') {
+          selectedExpert = runStepData.name;
+          console.log(`Routing to: ${selectedExpert}`);
+        }
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  // Create multi-agent run configuration
+  const runConfig: t.RunConfig = {
+    runId: `conditional-multi-agent-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    // Create and execute the run
+    const run = await Run.create(runConfig);
+
+    // Test with different types of questions
+    const testQuestions = [
+      'How do I implement a binary search tree in Python?',
+      'What are the key strategies for market expansion?',
+      'What is the capital of France?',
+    ];
+
+    const config = {
+      configurable: {
+        thread_id: 'conditional-conversation-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    for (const question of testQuestions) {
+      console.log(`\n--- Processing: "${question}" ---\n`);
+
+      // Reset for each question
+      selectedExpert = '';
+      conversationHistory.length = 0;
+      conversationHistory.push(new HumanMessage(question));
+
+      // Process with streaming
+      const inputs = {
+        messages: conversationHistory,
+      };
+
+      const finalContentParts = await run.processStream(inputs, config);
+      const finalMessages = run.getRunMessages();
+
+      if (finalMessages) {
+        conversationHistory.push(...finalMessages);
+      }
+
+      console.log(`\n\nExpert used: ${selectedExpert}`);
+      console.log('Content parts:', contentParts.length);
+      console.log('---');
+    }
+  } catch (error) {
+    console.error('Error in conditional multi-agent test:', error);
+  }
+}
+
+// Run the test
+testConditionalMultiAgent();

package/src/scripts/multi-agent-example-output.md

@@ -0,0 +1,110 @@
+# Multi-Agent Test Scripts - Example Output
+
+## multi-agent-test.ts
+
+```
+Testing Multi-Agent Handoff System...
+
+Invoking multi-agent graph...
+
+====== ON_RUN_STEP ======
+{ name: 'flight_assistant', type: 'agent', ... }
+[flight_assistant] Starting...
+
+====== CHAT_MODEL_STREAM ======
+I'll help you book a flight from Boston to New York...
+
+====== TOOL_START ======
+{ name: 'transfer_to_hotel_assistant', ... }
+
+====== ON_RUN_STEP_COMPLETED ======
+[flight_assistant] Completed
+
+====== ON_RUN_STEP ======
+{ name: 'hotel_assistant', type: 'agent', ... }
+[hotel_assistant] Starting...
+
+====== CHAT_MODEL_STREAM ======
+Great! I'll help you find a hotel near Times Square...
+
+Final content parts:
+[
+  { type: 'text', text: "I'll help you book a flight..." },
+  { type: 'tool_use', name: 'transfer_to_hotel_assistant', ... },
+  { type: 'text', text: "Great! I'll help you find a hotel..." }
+]
+```
+
+## multi-agent-parallel.ts
+
+```
+Testing Parallel Multi-Agent System (Fan-in/Fan-out)...
+
+Invoking parallel multi-agent graph...
+
+====== ON_RUN_STEP ======
+[researcher] Starting analysis...
+
+====== ON_RUN_STEP ======
+[analyst1] Starting analysis...
+[analyst2] Starting analysis...
+[analyst3] Starting analysis...
+
+====== CHAT_MODEL_STREAM ======
+[analyst1] From a financial perspective...
+[analyst2] From a technical perspective...
+[analyst3] From a market perspective...
+
+====== ON_RUN_STEP_COMPLETED ======
+[analyst1] Completed analysis
+[analyst2] Completed analysis
+[analyst3] Completed analysis
+
+====== ON_RUN_STEP ======
+[summarizer] Starting analysis...
+
+Final content parts: 5 parts
+```
+
+## multi-agent-conditional.ts
+
+```
+Testing Conditional Multi-Agent System...
+
+--- Processing: "How do I implement a binary search tree in Python?" ---
+
+====== ON_RUN_STEP ======
+{ name: 'classifier', type: 'agent', ... }
+
+====== ON_RUN_STEP ======
+{ name: 'technical_expert', type: 'agent', ... }
+Routing to: technical_expert
+
+====== CHAT_MODEL_STREAM ======
+To implement a binary search tree in Python, you'll need to create a Node class...
+
+Expert used: technical_expert
+Content parts: 2
+---
+
+--- Processing: "What are the key strategies for market expansion?" ---
+
+Routing to: business_expert
+...
+
+--- Processing: "What is the capital of France?" ---
+
+Routing to: general_assistant
+...
+```
+
+## Key Features of Updated Scripts
+
+1. **Proper Event Handling**: All GraphEvents are properly handled with custom handlers
+2. **Content Aggregation**: Using `createContentAggregator()` to collect all content parts
+3. **Stream Output**: Real-time token streaming via `ChatModelStreamHandler`
+4. **Debug Logging**: Comprehensive event logging for debugging multi-agent flows
+5. **Conversation History**: Proper tracking of messages across agent interactions
+6. **Return Content**: `returnContent: true` ensures content parts are returned
+
+The scripts now follow the same patterns as `simple.ts` and `tools.ts`, providing consistent behavior and comprehensive event handling across all multi-agent scenarios.