fix: Add error handling for null output and improve agent handoff workflow

Author: ciro-maciel

examples/guardrail.js

@@ -33,13 +33,30 @@ const minimumLengthGuardrail = outputGuardrail({
     name: "minimum_length_check",
     check: async (context, agent, output) => {
         const minimumLength = 20; // characters
-        const isTooShort = output.length < minimumLength;
+        
+        // Safely handle null/undefined output
+        if (!output) {
+            return {
+                output_info: {
+                    checked_for: "minimum length",
+                    required_length: minimumLength,
+                    actual_length: 0,
+                    is_too_short: true,
+                    error: "Output is null or undefined"
+                },
+                tripwire_triggered: true
+            };
+        }
+
+        // Convert output to string if it isn't already
+        const outputStr = String(output);
+        const isTooShort = outputStr.length < minimumLength;
 
         return {
             output_info: {
                 checked_for: "minimum length",
                 required_length: minimumLength,
-                actual_length: output.length,
+                actual_length: outputStr.length,
                 is_too_short: isTooShort
             },
             tripwire_triggered: isTooShort

examples/handoffs.js

@@ -3,25 +3,76 @@ const { Agent, Runner } = require('../src/index');
 // Set your OpenAI API key
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
 
+// Provider configuration
+const providerConfig = {
+    apiKey: OPENAI_API_KEY
+};
+
 async function main() {
+    // Create the Spanish agent with explicit configuration
     const spanishAgent = new Agent({
-        name: "Spanish Agent",
-        instructions: "You only speak Spanish.",
+        name: "Spanish_Agent",  // Use underscore for consistency
+        instructions: "You are a helpful assistant that only speaks Spanish. Always respond in Spanish to any questions or requests.",
+        model: "gpt-4",
+        provider: "openai",
+        providerConfig,
+        modelSettings: {
+            temperature: 0.7,
+            max_tokens: 500
+        }
     });
 
+    // Create the English agent with explicit configuration
     const englishAgent = new Agent({
-        name: "English Agent",
-        instructions: "You only speak English",
+        name: "English_Agent",  // Use underscore for consistency
+        instructions: "You are a helpful assistant that only speaks English. Always respond in English to any questions or requests.",
+        model: "gpt-4",
+        provider: "openai",
+        providerConfig,
+        modelSettings: {
+            temperature: 0.7,
+            max_tokens: 500
+        }
     });
 
+    // Create the triage agent with explicit configuration
     const triageAgent = new Agent({
-        name: "Triage Agent",
-        instructions: "Handoff to the appropriate agent based on the language of the request.",
+        name: "Triage_Agent",  // Use underscore for consistency
+        instructions: `You are a language triage agent. Your task is to analyze messages and route them to the appropriate language agent.
+
+Rules:
+1. For Spanish messages -> Use transfer_to_Spanish_Agent
+2. For English messages -> Use transfer_to_English_Agent
+3. DO NOT respond to the user directly
+4. ALWAYS use the appropriate transfer function
+5. If you detect Spanish, IMMEDIATELY call transfer_to_Spanish_Agent
+6. If you detect English, IMMEDIATELY call transfer_to_English_Agent`,
         handoffs: [spanishAgent, englishAgent],
+        model: "gpt-4",
+        provider: "openai",
+        providerConfig,
+        modelSettings: {
+            temperature: 0.7,
+            max_tokens: 500
+        }
     });
 
-    const result = await Runner.run(triageAgent, "Hola, ¿cómo estás?");
-    console.log(result.finalOutput);
+    try {
+        console.log('Sending message to triage agent...');
+        const result = await Runner.run(triageAgent, "Hola, ¿cómo estás?", {
+            maxTurns: 3,  // Allow for triage + response
+            context: { debug: true }
+        });
+        
+        console.log('\nFinal response:', result.finalOutput);
+        console.log('Last agent:', result.lastAgent.name);
+        console.log('\nMessage history:');
+        result.messages.forEach((msg, i) => {
+            console.log(`[${i}] ${msg.role}: ${msg.content}`);
+        });
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
 }
 
 main().catch(console.error);

src/providers/OpenAIProvider.js

@@ -38,10 +38,24 @@ class OpenAIProvider extends LLMProvider {
      * @returns {Array} - Formatted messages for OpenAI
      */
     formatMessages(messages) {
-        return messages.map(msg => ({
-            role: msg.role || 'user',
-            content: msg.content
-        }));
+        return messages.map(msg => {
+            const formattedMsg = {
+                role: msg.role || 'user',
+                content: msg.content || null
+            };
+
+            // Add tool calls if present
+            if (msg.tool_calls) {
+                formattedMsg.tool_calls = msg.tool_calls;
+            }
+
+            // Add tool call id if present
+            if (msg.tool_call_id) {
+                formattedMsg.tool_call_id = msg.tool_call_id;
+            }
+
+            return formattedMsg;
+        });
     }
 
     /**
@@ -54,13 +68,37 @@ class OpenAIProvider extends LLMProvider {
             throw new Error('Invalid response from OpenAI');
         }
 
-        return {
-            content: response.choices[0].message.content,
-            role: response.choices[0].message.role,
+        const message = response.choices[0].message;
+        const result = {
+            role: message.role,
             usage: response.usage,
             model: response.model,
             provider: 'openai'
         };
+
+        // Handle content (can be null for tool calls)
+        if (message.content !== undefined) {
+            result.content = message.content;
+        }
+
+        // Handle tool calls if present
+        if (message.tool_calls) {
+            result.tool_calls = message.tool_calls;
+        }
+
+        // Handle function call (legacy format) if present
+        if (message.function_call) {
+            result.tool_calls = [{
+                id: `call_${Date.now()}`,
+                type: 'function',
+                function: {
+                    name: message.function_call.name,
+                    arguments: message.function_call.arguments
+                }
+            }];
+        }
+
+        return result;
     }
 
     /**

src/runner.js

@@ -110,12 +110,26 @@ class Runner {
                             // Perform handoff
                             currentAgent = handoffAgent;
 
-                            // Add a system message indicating the handoff
-                            messages.push({
-                                role: 'system',
-                                content: `Handoff to ${handoffAgent.name}`
-                            });
-                            break; // Exit the tool call loop to restart with new agent
+                            // Reset messages for the new agent, keeping only the user's input
+                            const userMessages = messages.filter(msg => msg.role === 'user');
+                            messages = [
+                                { role: 'system', content: handoffAgent.instructions },
+                                ...userMessages
+                            ];
+
+                            // Get immediate response from new agent
+                            const handoffResponse = await handoffAgent.llmProvider.complete(
+                                messages,
+                                handoffAgent.modelSettings
+                            );
+                            
+                            // Set final output and add response to messages
+                            finalOutput = handoffResponse.content;
+                            messages.push(handoffResponse);
+                            
+                            // Exit the main loop since we have a final response
+                            currentTurn = maxTurns;
+                            break;
                         }
                     } else {
                         // Regular tool call