@illuma-ai/agents 1.0.81

package/src/scripts/single-agent-metadata-test.ts

@@ -0,0 +1,198 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import { v4 as uuidv4 } from 'uuid';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Single agent test with extensive metadata logging
+ * Compare with multi-agent-parallel-start.ts to see metadata differences
+ */
+async function testSingleAgent() {
+  console.log('Testing Single Agent with Metadata Logging...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent, contentMetadataMap } =
+    createContentAggregator();
+
+  const startTime = Date.now();
+
+  // Create custom handlers with extensive metadata logging
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  COMPLETED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  STARTED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_MESSAGE_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  // Create single-agent run configuration (standard graph, not multi-agent)
+  const runConfig: t.RunConfig = {
+    runId: `single-agent-${Date.now()}`,
+    graphConfig: {
+      type: 'standard',
+      llmConfig: {
+        provider: Providers.ANTHROPIC,
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a helpful AI assistant. Keep your response concise (50-100 words).`,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    // Create and execute the run
+    const run = await Run.create(runConfig);
+
+    // Debug: Log the graph structure
+    console.log('=== DEBUG: Graph Structure ===');
+    const graph = (run as any).Graph;
+    console.log('Graph exists:', !!graph);
+    if (graph) {
+      console.log('Graph type:', graph.constructor.name);
+      console.log('AgentContexts exists:', !!graph.agentContexts);
+      if (graph.agentContexts) {
+        console.log('AgentContexts size:', graph.agentContexts.size);
+        for (const [agentId, context] of graph.agentContexts) {
+          console.log(`\nAgent: ${agentId}`);
+          console.log(
+            `Tools: ${context.tools?.map((t: any) => t.name || 'unnamed').join(', ') || 'none'}`
+          );
+        }
+      }
+    }
+    console.log('=== END DEBUG ===\n');
+
+    const userMessage = `What are the best approaches to learning a new programming language?`;
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    console.log('Invoking single-agent graph...\n');
+
+    const config = {
+      configurable: {
+        thread_id: 'single-agent-conversation-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    // 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\n========== SUMMARY ==========');
+    console.log('Final content parts:', contentParts.length, 'parts');
+    console.log('\n=== Content Parts (clean, no metadata) ===');
+    console.dir(contentParts, { depth: null });
+    console.log(
+      '\n=== Content Metadata Map (should be empty for single-agent) ==='
+    );
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
+    console.log('====================================\n');
+
+    await sleep(3000);
+  } catch (error) {
+    console.error('Error in single-agent test:', error);
+  }
+}
+
+// Run the test
+testSingleAgent();

package/src/scripts/stream.ts

@@ -0,0 +1,140 @@
+/* eslint-disable no-console */
+// src/scripts/cli.ts
+import { config } from 'dotenv';
+config();
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler } from '@/events';
+
+import { getArgs } from '@/scripts/args';
+import { Run } from '@/run';
+import { GraphEvents, Callback } from '@/common';
+import { getLLMConfig } from '@/utils/llmConfig';
+
+const conversationHistory: BaseMessage[] = [];
+async function testStandardStreaming(): Promise<void> {
+  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_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      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 },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      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 => {
+        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 => {
+        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 => {
+        console.log('====== TOOL_START ======');
+        // console.dir(data, { depth: null });
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const run = await Run.create<t.IState>({
+    runId: 'test-run-id',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      tools: [],
+      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}.`,
+      streamBuffer: 3000,
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  const config = {
+    configurable: {
+      provider,
+      thread_id: 'conversation-num-1',
+    },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  console.log('Test 1: Weather query (content parts test)');
+
+  const userMessage = `
+  Make a search for the weather in ${location} today, which is ${currentDate}.
+  Before making the search, please let me know what you're about to do, then immediately start searching without hesitation.
+  Make sure to always refer to me by name, which is ${userName}.
+  After giving me a thorough summary, tell me a joke about the weather forecast we went over.
+  `;
+
+  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);
+});

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

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import { Run } from '@/run';
+import { Providers } from '@/common';
+import type * as t from '@/types';
+
+/**
+ * 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: t.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: 'handoff',
+          // Custom parameter name: "query"
+          prompt: 'The research question or topic to investigate',
+          promptKey: 'query',
+        },
+        {
+          from: 'supervisor',
+          to: 'designer',
+          edgeType: 'handoff',
+          // Custom parameter name: "requirements"
+          prompt: 'The design requirements and constraints',
+          promptKey: 'requirements',
+        },
+        {
+          from: 'supervisor',
+          to: 'coder',
+          edgeType: 'handoff',
+          // 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' as const,
+  };
+
+  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);

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

@@ -0,0 +1,170 @@
+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';
+import type * as t from '@/types';
+
+/**
+ * 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: 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.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;
+        if (toolData?.name?.includes('transfer_to_')) {
+          const specialist = toolData.name.replace('transfer_to_', '');
+          console.log(`\n🔀 Transferring to ${specialist}...`);
+          selectedRole = specialist;
+        }
+      },
+    },
+  };
+
+  const runConfig: t.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: 'handoff',
+          // 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' as const,
+  };
+
+  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);