@illuma-ai/agents 1.1.21 → 1.1.23

package/src/scripts/tool_search.js

@@ -1,114 +0,0 @@
-// src/scripts/tool_search.ts
-/**
- * Test script for the Tool Search Regex tool.
- * Run with: npm run tool_search
- *
- * Demonstrates runtime registry injection - the tool registry is passed
- * at invocation time, not at initialization time.
- */
-import { config } from 'dotenv';
-config();
-import { createToolSearch } from '@/tools/ToolSearch';
-import { createToolSearchToolRegistry } from '@/test/mockTools';
-async function runTest(searchTool, testName, query, options) {
-    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() {
-    console.log('Tool Search Regex - Test Script');
-    console.log('================================');
-    console.log('Demonstrating runtime tool registry injection\n');
-    const apiKey = process.env.CODE_EXECUTOR_API_KEY;
-    if (!apiKey) {
-        console.error('Error: CODE_EXECUTOR_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 = createToolSearch({ 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);
-});
-//# sourceMappingURL=tool_search.js.map

package/src/scripts/tools.js

@@ -1,125 +0,0 @@
-/* eslint-disable no-console */
-// src/scripts/cli.ts
-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 { getLLMConfig } from '@/utils/llmConfig';
-import { Calculator } from '@/tools/Calculator';
-import { getArgs } from '@/scripts/args';
-import { Run } from '@/run';
-const conversationHistory = [];
-async function testStandardStreaming() {
-    const { userName, location, provider, currentDate } = await getArgs();
-    const { contentParts, aggregateContent } = createContentAggregator();
-    const customHandlers = {
-        [GraphEvents.TOOL_END]: new ToolEndHandler(),
-        [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
-        [GraphEvents.CHAT_MODEL_START]: {
-            handle: (_event, _data, metadata) => {
-                console.log('\n====== CHAT_MODEL_START METADATA ======');
-                console.dir(metadata, { depth: null });
-            },
-        },
-        [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
-        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-            handle: (event, data, metadata) => {
-                console.log('====== ON_RUN_STEP_COMPLETED ======');
-                console.log('METADATA:');
-                console.dir(metadata, { depth: null });
-                aggregateContent({
-                    event,
-                    data: data,
-                });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP]: {
-            handle: (event, data, metadata) => {
-                console.log('====== ON_RUN_STEP ======');
-                console.log('DATA:');
-                console.dir(data, { depth: null });
-                console.log('METADATA:');
-                console.dir(metadata, { depth: null });
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_MESSAGE_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.ON_REASONING_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-            },
-        },
-        [GraphEvents.TOOL_START]: {
-            handle: (_event, data, metadata) => {
-                console.log('====== TOOL_START ======');
-                console.log('METADATA:');
-                console.dir(metadata, { depth: null });
-            },
-        },
-    };
-    const llmConfig = getLLMConfig(provider);
-    if (llmConfig.provider === Providers.BEDROCK) {
-        llmConfig.promptCache = true;
-    }
-    const run = await Run.create({
-        runId: 'test-run-id',
-        graphConfig: {
-            type: 'standard',
-            llmConfig,
-            tools: [new Calculator()],
-            instructions: 'You are a friendly AI assistant. Always address the user by their name.',
-            additional_instructions: `The user's name is ${userName} and they are located in ${location}.`,
-            maxContextTokens: 89000,
-        },
-        indexTokenCountMap: { 0: 35 },
-        returnContent: true,
-        skipCleanup: true,
-        customHandlers,
-    });
-    const config = {
-        configurable: {
-            provider,
-            thread_id: 'conversation-num-1',
-        },
-        streamMode: 'values',
-        version: 'v2',
-    };
-    console.log('Test 1: Calculation query');
-    const userMessage = `What is 1123123 + 123123 / 20348? After that, run some interesting calculations based off the result`;
-    conversationHistory.push(new HumanMessage(userMessage));
-    const inputs = {
-        messages: conversationHistory,
-    };
-    const finalContentParts = await run.processStream(inputs, config);
-    const finalMessages = run.getRunMessages();
-    if (finalMessages) {
-        conversationHistory.push(...finalMessages);
-        console.dir(conversationHistory, { depth: null });
-    }
-    // console.dir(finalContentParts, { depth: null });
-    console.log('\n\n====================\n\n');
-    console.dir(contentParts, { depth: null });
-}
-process.on('unhandledRejection', (reason, promise) => {
-    console.error('Unhandled Rejection at:', promise, 'reason:', reason);
-    console.log('Conversation history:');
-    process.exit(1);
-});
-testStandardStreaming().catch((err) => {
-    console.error(err);
-    console.log('Conversation history:');
-    console.dir(conversationHistory, { depth: null });
-    process.exit(1);
-});
-//# sourceMappingURL=tools.js.map

package/src/specs/agent-handoffs-bedrock.integration.test.js

@@ -1,280 +0,0 @@
-/**
- * Integration test: Agent Handoff with Bedrock
- *
- * Verifies end-to-end that:
- * 1. Handoff tool descriptions are enriched with agent name + description
- * 2. The LLM (Bedrock Claude) can see and use these descriptions to route correctly
- * 3. The handoff actually transfers control to the correct agent
- *
- * Requires: BEDROCK_AWS_ACCESS_KEY_ID, BEDROCK_AWS_SECRET_ACCESS_KEY, BEDROCK_AWS_REGION
- */
-import { config } from 'dotenv';
-import { resolve } from 'path';
-// Load from local .env first, then fall back to ranger's .env for Bedrock credentials
-config();
-config({
-    path: resolve(process.cwd(), '..', 'ranger', '.env'),
-    override: false,
-});
-import { HumanMessage } from '@langchain/core/messages';
-import { Providers, Constants, GraphEvents } from '@/common';
-import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-import { Run } from '@/run';
-const bedrockRegion = process.env.BEDROCK_AWS_REGION != null &&
-    process.env.BEDROCK_AWS_REGION !== ''
-    ? process.env.BEDROCK_AWS_REGION
-    : process.env.BEDROCK_AWS_DEFAULT_REGION;
-const hasBedrock = process.env.BEDROCK_AWS_ACCESS_KEY_ID != null &&
-    process.env.BEDROCK_AWS_ACCESS_KEY_ID !== '' &&
-    process.env.BEDROCK_AWS_SECRET_ACCESS_KEY != null &&
-    process.env.BEDROCK_AWS_SECRET_ACCESS_KEY !== '' &&
-    bedrockRegion != null &&
-    bedrockRegion !== '';
-const describeIf = hasBedrock ? describe : describe.skip;
-/** Helper to safely get tool description from tool object */
-const getToolDescription = (tool) => {
-    return tool.description;
-};
-/** Helper to safely get tool name from tool object */
-const getToolName = (tool) => {
-    return tool.name;
-};
-/** Helper to find tool by name */
-const findToolByName = (tools, name) => {
-    return tools?.find((tool) => getToolName(tool) === name);
-};
-describeIf('Agent Handoff E2E with Bedrock', () => {
-    jest.setTimeout(120000);
-    const bedrockOptions = {
-        model: 'us.anthropic.claude-3-5-haiku-20241022-v1:0',
-        region: bedrockRegion != null && bedrockRegion !== ''
-            ? bedrockRegion
-            : 'us-east-1',
-        credentials: {
-            accessKeyId: process.env.BEDROCK_AWS_ACCESS_KEY_ID,
-            secretAccessKey: process.env.BEDROCK_AWS_SECRET_ACCESS_KEY,
-        },
-    };
-    const createBedrockAgent = (agentId, name, description, instructions) => ({
-        agentId,
-        name,
-        description,
-        provider: Providers.BEDROCK,
-        clientOptions: bedrockOptions,
-        instructions,
-        maxContextTokens: 28000,
-    });
-    describe('Tool Description Enrichment (no edge.description)', () => {
-        it('should generate tool descriptions from agent name + description when edge has no description', async () => {
-            const agents = [
-                createBedrockAgent('supervisor_abc123', 'Supervisor', 'Routes requests to specialists', 'You are a supervisor. Route requests to the appropriate specialist.'),
-                createBedrockAgent('agent_W47hBnn2RoVZEOy5595GC', 'Sales Expert', 'Handles product pricing, quotes, and purchase orders for enterprise clients', 'You are a sales expert.'),
-                createBedrockAgent('agent_X92kLmn4TpQR8vw3221HD', 'Technical Support', 'Troubleshoots technical issues, resolves bugs, and handles escalations', 'You are a technical support agent.'),
-            ];
-            // Edges WITHOUT explicit descriptions - simulates what happens in production
-            // when users add handoffs through the UI without typing descriptions
-            const edges = [
-                {
-                    from: 'supervisor_abc123',
-                    to: 'agent_W47hBnn2RoVZEOy5595GC',
-                    edgeType: 'handoff',
-                    // No description - should auto-generate from agent name + description
-                },
-                {
-                    from: 'supervisor_abc123',
-                    to: 'agent_X92kLmn4TpQR8vw3221HD',
-                    edgeType: 'handoff',
-                    // No description
-                },
-            ];
-            const run = await Run.create({
-                runId: `bedrock-handoff-desc-${Date.now()}`,
-                graphConfig: {
-                    type: 'multi-agent',
-                    agents,
-                    edges,
-                },
-                returnContent: true,
-            });
-            const supervisorContext = run.Graph.agentContexts.get('supervisor_abc123');
-            // Verify the handoff tools have enriched descriptions
-            const salesTool = findToolByName(supervisorContext?.tools, `${Constants.LC_TRANSFER_TO_}agent_W47hBnn2RoVZEOy5595GC`);
-            const supportTool = findToolByName(supervisorContext?.tools, `${Constants.LC_TRANSFER_TO_}agent_X92kLmn4TpQR8vw3221HD`);
-            expect(salesTool).toBeDefined();
-            expect(supportTool).toBeDefined();
-            const salesDesc = getToolDescription(salesTool);
-            const supportDesc = getToolDescription(supportTool);
-            // CRITICAL: Descriptions must NOT be just "Transfer control to agent 'agent_W47hBnn...'"
-            // They must include the human-readable name and description
-            expect(salesDesc).toContain('Sales Expert');
-            expect(salesDesc).toContain('pricing');
-            expect(salesDesc).not.toContain('agent_W47hBnn2RoVZEOy5595GC');
-            expect(supportDesc).toContain('Technical Support');
-            expect(supportDesc).toContain('Troubleshoots');
-            expect(supportDesc).not.toContain('agent_X92kLmn4TpQR8vw3221HD');
-            /* eslint-disable no-console */
-            console.log('[PASS] Sales tool description:', salesDesc);
-            console.log('[PASS] Support tool description:', supportDesc);
-            /* eslint-enable no-console */
-        });
-    });
-    describe('Live Bedrock Handoff Routing', () => {
-        it('should route a sales question to the Sales Expert agent', async () => {
-            const agents = [
-                createBedrockAgent('router', 'Router', 'Routes user requests to specialists', `You are a request router. You must analyze the user's message and transfer to the appropriate specialist.
-
-          IMPORTANT: Do NOT answer the question yourself. You MUST use one of your transfer tools to hand off to a specialist.
-          Pick the specialist whose description best matches the user's request.`),
-                createBedrockAgent('sales_agent', 'Sales Expert', 'Handles product pricing, quotes, and purchase orders', 'You are a sales expert. Answer questions about pricing and products. Be concise.'),
-                createBedrockAgent('support_agent', 'Technical Support', 'Troubleshoots technical issues and resolves bugs', 'You are technical support. Help with technical problems. Be concise.'),
-            ];
-            const edges = [
-                { from: 'router', to: 'sales_agent', edgeType: 'handoff' },
-                { from: 'router', to: 'support_agent', edgeType: 'handoff' },
-            ];
-            const { contentParts: _contentParts, aggregateContent } = createContentAggregator();
-            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) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-                [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-                    handle: (event, data) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-                [GraphEvents.ON_MESSAGE_DELTA]: {
-                    handle: (event, data) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-            };
-            const run = await Run.create({
-                runId: `bedrock-live-handoff-${Date.now()}`,
-                graphConfig: {
-                    type: 'multi-agent',
-                    agents,
-                    edges,
-                },
-                customHandlers,
-                returnContent: true,
-            });
-            const config = {
-                configurable: { thread_id: 'bedrock-handoff-test' },
-                streamMode: 'values',
-                version: 'v2',
-            };
-            // Send a sales-related question
-            const messages = [
-                new HumanMessage('What is the pricing for your enterprise plan?'),
-            ];
-            await run.processStream({ messages }, config);
-            const finalMessages = run.getRunMessages();
-            expect(finalMessages).toBeDefined();
-            expect(finalMessages.length).toBeGreaterThan(1);
-            // Verify the handoff happened to the sales agent (not support)
-            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
-            const salesHandoff = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}sales_agent`);
-            const supportHandoff = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}support_agent`);
-            expect(salesHandoff).toBeDefined();
-            expect(supportHandoff).toBeUndefined();
-            /* eslint-disable no-console */
-            console.log('[PASS] Router correctly handed off to Sales Expert');
-            console.log('[PASS] Handoff tool message:', salesHandoff?.content);
-            /* eslint-enable no-console */
-            // Verify the sales agent actually responded
-            const aiMessages = finalMessages.filter((msg) => msg.getType() === 'ai');
-            expect(aiMessages.length).toBeGreaterThanOrEqual(2); // Router + Sales responses
-        });
-        it('should route a technical question to the Support agent', async () => {
-            const agents = [
-                createBedrockAgent('router', 'Router', 'Routes user requests to specialists', `You are a request router. You must analyze the user's message and transfer to the appropriate specialist.
-
-          IMPORTANT: Do NOT answer the question yourself. You MUST use one of your transfer tools to hand off to a specialist.
-          Pick the specialist whose description best matches the user's request.`),
-                createBedrockAgent('sales_agent', 'Sales Expert', 'Handles product pricing, quotes, and purchase orders', 'You are a sales expert. Answer questions about pricing. Be concise.'),
-                createBedrockAgent('support_agent', 'Technical Support', 'Troubleshoots technical issues, resolves bugs, and handles error messages', 'You are technical support. Help with technical problems. Be concise.'),
-            ];
-            const edges = [
-                { from: 'router', to: 'sales_agent', edgeType: 'handoff' },
-                { from: 'router', to: 'support_agent', edgeType: 'handoff' },
-            ];
-            const { contentParts: _contentParts, aggregateContent } = createContentAggregator();
-            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) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-                [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-                    handle: (event, data) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-                [GraphEvents.ON_MESSAGE_DELTA]: {
-                    handle: (event, data) => {
-                        aggregateContent({
-                            event: event,
-                            data: data,
-                        });
-                    },
-                },
-            };
-            const run = await Run.create({
-                runId: `bedrock-live-handoff-support-${Date.now()}`,
-                graphConfig: {
-                    type: 'multi-agent',
-                    agents,
-                    edges,
-                },
-                customHandlers,
-                returnContent: true,
-            });
-            const config = {
-                configurable: { thread_id: 'bedrock-handoff-support-test' },
-                streamMode: 'values',
-                version: 'v2',
-            };
-            // Send a technical question
-            const messages = [
-                new HumanMessage('I am getting an error 500 when trying to login. The page crashes after entering my password.'),
-            ];
-            await run.processStream({ messages }, config);
-            const finalMessages = run.getRunMessages();
-            expect(finalMessages).toBeDefined();
-            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
-            const supportHandoff = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}support_agent`);
-            const salesHandoff = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}sales_agent`);
-            expect(supportHandoff).toBeDefined();
-            expect(salesHandoff).toBeUndefined();
-            /* eslint-disable no-console */
-            console.log('[PASS] Router correctly handed off to Technical Support');
-            console.log('[PASS] Handoff tool message:', supportHandoff?.content);
-            /* eslint-enable no-console */
-        });
-    });
-});
-//# sourceMappingURL=agent-handoffs-bedrock.integration.test.js.map