@illuma-ai/agents 1.1.20 → 1.1.22

package/src/scripts/test-custom-prompt-key.js

@@ -1,132 +0,0 @@
-#!/usr/bin/env bun
-import { config } from 'dotenv';
-config();
-import { HumanMessage } from '@langchain/core/messages';
-import { Run } from '@/run';
-import { Providers } from '@/common';
-/**
- * Test the custom promptKey feature for handoff edges
- * This demonstrates how to use custom parameter names instead of "instructions"
- */
-async function testCustomPromptKey() {
-    console.log('Testing Custom Prompt Key Feature...\n');
-    const runConfig = {
-        runId: `test-custom-prompt-key-${Date.now()}`,
-        graphConfig: {
-            type: 'multi-agent',
-            agents: [
-                {
-                    agentId: 'supervisor',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Task Supervisor managing different agents:
-          
-          1. transfer_to_researcher - For research tasks (uses "query" parameter)
-          2. transfer_to_designer - For design tasks (uses "requirements" parameter)
-          3. transfer_to_coder - For coding tasks (uses "specification" parameter)
-          
-          Each agent expects different parameter names in their handoff tools.
-          Pay attention to the parameter names when calling each tool.`,
-                    maxContextTokens: 8000,
-                },
-                {
-                    agentId: 'researcher',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Research Agent. You receive research queries to investigate.
-          Look for the "Query:" field in the transfer message.`,
-                    maxContextTokens: 8000,
-                },
-                {
-                    agentId: 'designer',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Design Agent. You receive design requirements to implement.
-          Look for the "Requirements:" field in the transfer message.`,
-                    maxContextTokens: 8000,
-                },
-                {
-                    agentId: 'coder',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Coding Agent. You receive technical specifications to implement.
-          Look for the "Specification:" field in the transfer message.`,
-                    maxContextTokens: 8000,
-                },
-            ],
-            edges: [
-                {
-                    from: 'supervisor',
-                    to: 'researcher',
-                    edgeType: 'transfer',
-                    // Custom parameter name: "query"
-                    prompt: 'The research question or topic to investigate',
-                    promptKey: 'query',
-                },
-                {
-                    from: 'supervisor',
-                    to: 'designer',
-                    edgeType: 'transfer',
-                    // Custom parameter name: "requirements"
-                    prompt: 'The design requirements and constraints',
-                    promptKey: 'requirements',
-                },
-                {
-                    from: 'supervisor',
-                    to: 'coder',
-                    edgeType: 'transfer',
-                    // Custom parameter name: "specification"
-                    prompt: 'The technical specification for the code to implement',
-                    promptKey: 'specification',
-                },
-            ],
-        },
-    };
-    const run = await Run.create(runConfig);
-    // Test queries for different agents
-    const testQueries = [
-        // 'Research the latest trends in sustainable energy storage technologies',
-        'Design a mobile app interface for a fitness tracking application',
-        // 'Write a Python function that calculates the Fibonacci sequence recursively',
-    ];
-    const config = {
-        configurable: {
-            thread_id: 'custom-prompt-key-test-1',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    for (const query of testQueries) {
-        console.log(`\n${'='.repeat(60)}`);
-        console.log(`USER QUERY: "${query}"`);
-        console.log('='.repeat(60));
-        const inputs = {
-            messages: [new HumanMessage(query)],
-        };
-        await run.processStream(inputs, config);
-        console.log(`\n${'─'.repeat(60)}`);
-        console.log('Each agent receives instructions via their custom parameter:');
-        console.log('- Researcher expects "query"');
-        console.log('- Designer expects "requirements"');
-        console.log('- Coder expects "specification"');
-        console.log('─'.repeat(60));
-    }
-    console.log('\n\nDemonstration complete!');
-    console.log('The promptKey feature allows for more semantic parameter names');
-    console.log('that better match the domain and purpose of each agent.');
-}
-// Run the test
-testCustomPromptKey().catch(console.error);
-//# sourceMappingURL=test-custom-prompt-key.js.map

package/src/scripts/test-handoff-input.js

@@ -1,143 +0,0 @@
-import { config } from 'dotenv';
-config();
-import { HumanMessage } from '@langchain/core/messages';
-import { Run } from '@/run';
-import { Providers, GraphEvents } from '@/common';
-import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-/**
- * Test the new handoff input feature using the prompt field
- * This demonstrates how supervisors can pass specific instructions to specialists
- */
-async function testHandoffInput() {
-    console.log('Testing Handoff Input Feature...\n');
-    // Set up content aggregator
-    const { contentParts, aggregateContent } = createContentAggregator();
-    // Track which specialist role was selected
-    let selectedRole = '';
-    let roleInstructions = '';
-    // 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, data) => {
-                const runStepData = data;
-                if (runStepData?.name) {
-                    console.log(`\n[${runStepData.name}] Processing...`);
-                }
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-            handle: (event, data) => {
-                aggregateContent({
-                    event,
-                    data: data,
-                });
-            },
-        },
-        [GraphEvents.ON_MESSAGE_DELTA]: {
-            handle: (event, data) => {
-                console.dir(data, { depth: null });
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.TOOL_START]: {
-            handle: (_event, data, metadata) => {
-                const toolData = data;
-                if (toolData?.name?.includes('transfer_to_')) {
-                    const specialist = toolData.name.replace('transfer_to_', '');
-                    console.log(`\n🔀 Transferring to ${specialist}...`);
-                    selectedRole = specialist;
-                }
-            },
-        },
-    };
-    const runConfig = {
-        customHandlers,
-        runId: `test-handoff-input-${Date.now()}`,
-        graphConfig: {
-            type: 'multi-agent',
-            agents: [
-                {
-                    agentId: 'supervisor',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Task Supervisor. You have access to two specialist agents:
-          
-          1. transfer_to_analyst - For data analysis tasks
-          2. transfer_to_writer - For content creation tasks
-          
-          When transferring to a specialist, you MUST provide specific instructions
-          in the tool call to guide their work. Be detailed about what you need.`,
-                    maxContextTokens: 8000,
-                },
-                {
-                    agentId: 'analyst',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Data Analyst. Follow the supervisor's instructions carefully.
-          When you receive instructions, acknowledge them and perform the requested analysis.`,
-                    maxContextTokens: 8000,
-                },
-                {
-                    agentId: 'writer',
-                    provider: Providers.ANTHROPIC,
-                    clientOptions: {
-                        modelName: 'claude-haiku-4-5',
-                        apiKey: process.env.ANTHROPIC_API_KEY,
-                    },
-                    instructions: `You are a Content Writer. Follow the supervisor's instructions carefully.
-          When you receive instructions, acknowledge them and create the requested content.`,
-                    maxContextTokens: 8000,
-                },
-            ],
-            edges: [
-                {
-                    from: 'supervisor',
-                    to: ['analyst', 'writer'],
-                    edgeType: 'transfer',
-                    // This prompt field now serves as the description for the input parameter
-                    prompt: 'Specific instructions for the specialist to follow. Be detailed about what analysis to perform, what data to focus on, or what content to create.',
-                },
-            ],
-        },
-    };
-    const run = await Run.create(runConfig);
-    // Test queries that should result in different handoffs with specific instructions
-    const testQueries = [
-        // 'Analyze our Q4 sales data and identify the top 3 performing products',
-        'Write a blog post about the benefits of remote work for software developers',
-    ];
-    const config = {
-        configurable: {
-            thread_id: 'handoff-input-test-1',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    for (const query of testQueries) {
-        console.log(`\n${'='.repeat(60)}`);
-        console.log(`USER QUERY: "${query}"`);
-        console.log('='.repeat(60));
-        const inputs = {
-            messages: [new HumanMessage(query)],
-        };
-        const finalContentParts = await run.processStream(inputs, config);
-        console.log(`\n${'─'.repeat(60)}`);
-        console.log('Notice how the supervisor passes specific instructions');
-        console.log('to the specialist through the handoff tool input parameter.');
-        console.log('─'.repeat(60));
-    }
-}
-// Run the test
-testHandoffInput().catch(console.error);
-//# sourceMappingURL=test-handoff-input.js.map

package/src/scripts/test-handoff-preamble.js

@@ -1,227 +0,0 @@
-/**
- * Test script for multi-turn handoff behavior.
- *
- * This tests the fix for the issue where receiving agents would see transfer messages
- * and prematurely produce end tokens, thinking the work was already done.
- *
- * The fix:
- * 1. Filters out transfer tool calls and ToolMessages from the receiving agent's context
- * 2. Injects any passthrough instructions as a HumanMessage to ground the receiving agent
- */
-import { config } from 'dotenv';
-config();
-import { HumanMessage } from '@langchain/core/messages';
-import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-import { GraphEvents, Providers } from '@/common';
-import { Run } from '@/run';
-const conversationHistory = [];
-/**
- * Test multi-turn handoff between a coordinator and a specialist
- */
-async function testHandoffPreamble() {
-    console.log('='.repeat(60));
-    console.log('Testing Multi-Turn Handoff with Preamble Injection');
-    console.log('='.repeat(60));
-    console.log('\nThis test verifies that:');
-    console.log('1. Transfer messages are filtered from receiving agent context');
-    console.log('2. Passthrough instructions are injected as a HumanMessage');
-    console.log('3. Multi-turn conversations work correctly after handoffs\n');
-    const { contentParts, aggregateContent } = createContentAggregator();
-    /** Track which agent is responding */
-    let currentAgent = '';
-    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, data) => {
-                const runStep = data;
-                if (runStep.agentId) {
-                    currentAgent = runStep.agentId;
-                    console.log(`\n[Agent: ${currentAgent}] Processing...`);
-                }
-                aggregateContent({ event, data: runStep });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-            handle: (event, data) => {
-                aggregateContent({
-                    event,
-                    data: data,
-                });
-            },
-        },
-        [GraphEvents.ON_MESSAGE_DELTA]: {
-            handle: (event, data) => {
-                console.log('====== ON_MESSAGE_DELTA ======');
-                console.dir(data, { depth: null });
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.TOOL_START]: {
-            handle: (_event, data, _metadata) => {
-                const toolData = data;
-                if (toolData?.name?.includes('transfer_to_')) {
-                    const specialist = toolData.name.replace('lc_transfer_to_', '');
-                    console.log(`\n🔀 Handing off to: ${specialist}`);
-                }
-            },
-        },
-    };
-    /**
-     * Create agents:
-     * - coordinator: Decides when to hand off to specialist
-     * - specialist: Handles specific tasks delegated by coordinator
-     */
-    const agents = [
-        {
-            agentId: 'coordinator',
-            provider: Providers.OPENAI,
-            clientOptions: {
-                modelName: 'gpt-4.1-mini',
-                apiKey: process.env.OPENAI_API_KEY,
-            },
-            instructions: `You are a Task Coordinator. Your role is to:
-1. Understand user requests
-2. If the request involves technical analysis, use the transfer_to_specialist tool to hand off
-3. When handing off, provide clear instructions about what needs to be done
-
-IMPORTANT: When using the handoff tool, include specific instructions for the specialist.`,
-            maxContextTokens: 8000,
-        },
-        {
-            agentId: 'specialist',
-            provider: Providers.OPENAI,
-            clientOptions: {
-                modelName: 'gpt-4.1-mini',
-                apiKey: process.env.OPENAI_API_KEY,
-            },
-            instructions: `You are a Technical Specialist. When you receive a request:
-1. Carefully read any instructions provided
-2. Provide a detailed technical response
-3. Do NOT just acknowledge - provide substantive help
-
-IMPORTANT: You are the specialist - provide a complete, helpful response to the task.`,
-            maxContextTokens: 8000,
-        },
-    ];
-    /** Create handoff edge with passthrough instructions */
-    const edges = [
-        {
-            from: 'coordinator',
-            to: 'specialist',
-            description: 'Transfer to technical specialist for analysis',
-            edgeType: 'transfer',
-            prompt: 'Specific instructions for the specialist about what to analyze',
-            promptKey: 'instructions',
-        },
-    ];
-    const runConfig = {
-        runId: `handoff-test-${Date.now()}`,
-        graphConfig: {
-            type: 'multi-agent',
-            agents,
-            edges,
-        },
-        customHandlers,
-        returnContent: true,
-        skipCleanup: true,
-    };
-    const run = await Run.create(runConfig);
-    const config = {
-        configurable: {
-            thread_id: 'handoff-test-conversation-1',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    /** TURN 1: Initial request that triggers handoff */
-    console.log('\n' + '─'.repeat(60));
-    console.log('TURN 1: Initial request (should trigger handoff)');
-    console.log('─'.repeat(60));
-    const userMessage1 = `
-    Hi! Can you help me understand the time complexity of quicksort?
-    I need a technical explanation.
-  `;
-    conversationHistory.push(new HumanMessage(userMessage1));
-    console.log('\nUser:', userMessage1.trim());
-    console.log('\nResponse:');
-    let inputs = { messages: conversationHistory };
-    await run.processStream(inputs, config);
-    const messages1 = run.getRunMessages();
-    if (messages1) {
-        conversationHistory.push(...messages1);
-    }
-    console.log('\n');
-    /** TURN 2: Follow-up question to test multi-turn after handoff */
-    console.log('\n' + '─'.repeat(60));
-    console.log('TURN 2: Follow-up question (tests context after handoff)');
-    console.log('─'.repeat(60));
-    const userMessage2 = `
-    Thanks! Can you also explain the space complexity and when quicksort 
-    might not be the best choice?
-  `;
-    conversationHistory.push(new HumanMessage(userMessage2));
-    console.log('\nUser:', userMessage2.trim());
-    console.log('\nResponse:');
-    inputs = { messages: conversationHistory };
-    await run.processStream(inputs, config);
-    const messages2 = run.getRunMessages();
-    if (messages2) {
-        conversationHistory.push(...messages2);
-    }
-    console.log('\n');
-    /** TURN 3: Another follow-up to verify sustained conversation */
-    console.log('\n' + '─'.repeat(60));
-    console.log('TURN 3: Third turn (tests sustained multi-turn)');
-    console.log('─'.repeat(60));
-    const userMessage3 = `
-    Great explanation! One more question - how does quicksort compare 
-    to mergesort in practice?
-  `;
-    conversationHistory.push(new HumanMessage(userMessage3));
-    console.log('\nUser:', userMessage3.trim());
-    console.log('\nResponse:');
-    inputs = { messages: conversationHistory };
-    await run.processStream(inputs, config);
-    const messages3 = run.getRunMessages();
-    if (messages3) {
-        conversationHistory.push(...messages3);
-    }
-    /** Summary */
-    console.log('\n\n' + '='.repeat(60));
-    console.log('TEST SUMMARY');
-    console.log('='.repeat(60));
-    console.log('\nTotal messages in conversation:', conversationHistory.length);
-    console.log('\nMessage types:');
-    for (let i = 0; i < conversationHistory.length; i++) {
-        const msg = conversationHistory[i];
-        const type = msg.getType();
-        const preview = typeof msg.content === 'string'
-            ? msg.content.slice(0, 50).replace(/\n/g, ' ')
-            : '[complex content]';
-        console.log(`  ${i + 1}. [${type}] ${preview}...`);
-    }
-    console.log('\n✅ Test completed. Review the output above to verify:');
-    console.log('   - Specialist received and acted on instructions');
-    console.log('   - No premature end tokens after handoff');
-    console.log('   - Multi-turn conversation continued smoothly');
-    console.dir(contentParts, { depth: null });
-}
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-    console.log('\nConversation history at failure:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-process.on('uncaughtException', (err) => {
-    console.error('Uncaught Exception:', err);
-});
-testHandoffPreamble().catch((err) => {
-    console.error('Test failed:', err);
-    console.log('\nConversation history at failure:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-//# sourceMappingURL=test-handoff-preamble.js.map