@illuma-ai/agents 1.4.0-alpha.5 → 1.5.0

package/src/scripts/test-bedrock-handoff-autonomous.ts

@@ -1,267 +0,0 @@
-/**
- * Integration test: Autonomous Handoff with Bedrock
- *
- * Tests the full autonomous handoff pattern where:
- * 1. Orchestrator receives user request
- * 2. Orchestrator delegates to specialist via handoff (subgraph.invoke)
- * 3. Specialist completes work and returns result to orchestrator
- * 4. Orchestrator synthesizes and responds
- *
- * This validates:
- * - Handoff-only children don't cause UNREACHABLE_NODE errors
- * - stripOrphanedToolUse prevents Bedrock tool_use/tool_result mismatch
- * - Empty tool descriptions are sanitized for Bedrock
- * - Orchestrator receives child result and produces final response
- *
- * Requires: BEDROCK_AWS_ACCESS_KEY_ID, BEDROCK_AWS_SECRET_ACCESS_KEY, BEDROCK_AWS_REGION
- */
-import { config } from 'dotenv';
-config();
-import { resolve } from 'path';
-if (process.env.AGENTS_TEST_ENV_PATH) {
-  config({
-    path: resolve(process.env.AGENTS_TEST_ENV_PATH),
-    override: false,
-  });
-}
-
-// Disable observability for this test (requires @illuma-ai/observability-node)
-delete process.env.ILLUMA_SECRET_KEY;
-delete process.env.ILLUMA_PUBLIC_KEY;
-delete process.env.ILLUMA_BASE_URL;
-
-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';
-import type { RunnableConfig } from '@langchain/core/runnables';
-
-const bedrockRegion =
-  process.env.BEDROCK_AWS_REGION ??
-  process.env.BEDROCK_AWS_DEFAULT_REGION ??
-  'us-east-1';
-
-const bedrockOptions = {
-  model: 'us.anthropic.claude-3-5-haiku-20241022-v1:0',
-  region: bedrockRegion,
-  credentials: {
-    accessKeyId: process.env.BEDROCK_AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.BEDROCK_AWS_SECRET_ACCESS_KEY!,
-  },
-};
-
-function createBedrockAgent(
-  agentId: string,
-  name: string,
-  description: string,
-  instructions: string
-): t.AgentInputs {
-  return {
-    agentId,
-    name,
-    description,
-    provider: Providers.BEDROCK,
-    clientOptions: bedrockOptions,
-    instructions,
-    maxContextTokens: 16000,
-  };
-}
-
-async function testAutonomousHandoff() {
-  console.log('=== Autonomous Handoff with Bedrock ===\n');
-
-  const agents: t.AgentInputs[] = [
-    createBedrockAgent(
-      'orchestrator',
-      'Orchestrator',
-      'Routes complex requests to specialist agents and synthesizes results',
-      `You are an autonomous orchestrator. Break down user requests and delegate to specialists using your handoff tools.
-
-IMPORTANT: You MUST use your handoff tools to delegate work. Do NOT answer questions yourself.
-- Use lc_handoff_to_researcher for any information gathering or research tasks
-- Use lc_handoff_to_writer for any content creation tasks
-
-After receiving results from a specialist, synthesize and present the final answer to the user.`
-    ),
-    createBedrockAgent(
-      'researcher',
-      'Researcher',
-      'Finds and analyzes information on any topic',
-      `You are a research specialist. When you receive a request:
-1. Analyze what information is needed
-2. Provide a structured, factual response with key findings
-3. Be concise but thorough — aim for 3-5 key points
-
-Do NOT delegate or transfer. Just do the research and respond.`
-    ),
-    createBedrockAgent(
-      'writer',
-      'Writer',
-      'Creates professional written content',
-      `You are a professional writer. When you receive a request:
-1. Create well-structured, clear content
-2. Use appropriate tone and format
-3. Be concise
-
-Do NOT delegate or transfer. Just write the content and respond.`
-    ),
-  ];
-
-  const edges: t.GraphEdge[] = [
-    { from: 'orchestrator', to: 'researcher', edgeType: 'handoff' },
-    { from: 'orchestrator', to: 'writer', edgeType: 'handoff' },
-  ];
-
-  // Set up content aggregator and handlers
-  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]: {
-      handle: (event: string, data: t.StreamEventData): void => {
-        aggregateContent({
-          event: event as GraphEvents,
-          data: data as t.RunStep,
-        });
-      },
-    },
-    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-      handle: (event: string, data: t.StreamEventData): void => {
-        aggregateContent({
-          event: event as GraphEvents,
-          data: data as unknown as { result: t.ToolEndEvent },
-        });
-      },
-    },
-    [GraphEvents.ON_MESSAGE_DELTA]: {
-      handle: (event: string, data: t.StreamEventData): void => {
-        aggregateContent({
-          event: event as GraphEvents,
-          data: data as t.MessageDeltaEvent,
-        });
-      },
-    },
-  };
-
-  const run = await Run.create({
-    runId: `bedrock-autonomous-handoff-${Date.now()}`,
-    graphConfig: {
-      type: 'multi-agent',
-      agents,
-      edges,
-    },
-    customHandlers,
-    returnContent: true,
-  });
-
-  const streamConfig: Partial<RunnableConfig> & {
-    version: 'v1' | 'v2';
-    streamMode: string;
-  } = {
-    configurable: { thread_id: 'bedrock-autonomous-test' },
-    streamMode: 'values',
-    version: 'v2',
-  };
-
-  // ── Test 1: Single handoff (Orchestrator → Researcher → back) ──
-  console.log('\n--- Test 1: Single Handoff (Research) ---');
-  console.log(
-    'Query: "What are the top 3 trends in enterprise AI adoption in 2025?"'
-  );
-
-  const messages1 = [
-    new HumanMessage(
-      'What are the top 3 trends in enterprise AI adoption in 2025?'
-    ),
-  ];
-
-  try {
-    await run.processStream({ messages: messages1 }, streamConfig);
-
-    const finalMessages = run.getRunMessages();
-    console.log(
-      `\n✓ Graph completed. Total messages: ${finalMessages?.length ?? 0}`
-    );
-
-    // Check that a handoff happened
-    const lastMsg = finalMessages?.[finalMessages.length - 1];
-    if (lastMsg) {
-      const content =
-        typeof lastMsg.content === 'string'
-          ? lastMsg.content
-          : JSON.stringify(lastMsg.content);
-      console.log(
-        `\n✓ Final response (first 500 chars):\n${content.slice(0, 500)}`
-      );
-    }
-
-    // Verify last active agent tracking
-    const lastActiveAgentId = run.getLastActiveAgentId?.();
-    console.log(`\n✓ lastActiveAgentId: ${lastActiveAgentId}`);
-
-    console.log('\n✅ Test 1 PASSED — Single handoff completed successfully');
-  } catch (err) {
-    console.error('\n❌ Test 1 FAILED:', (err as Error).message);
-    console.error((err as Error).stack);
-  }
-
-  // ── Test 2: Multi-hop (Orchestrator → Researcher → back → Writer → back) ──
-  console.log('\n\n--- Test 2: Multi-Hop Handoff (Research → Write) ---');
-  console.log(
-    'Query: "Research AI agent frameworks and write a brief summary email"'
-  );
-
-  const run2 = await Run.create({
-    runId: `bedrock-autonomous-handoff-2-${Date.now()}`,
-    graphConfig: {
-      type: 'multi-agent',
-      agents,
-      edges,
-    },
-    returnContent: true,
-  });
-
-  const messages2 = [
-    new HumanMessage(
-      'Research the latest AI agent frameworks and write a brief 3-sentence summary.'
-    ),
-  ];
-
-  try {
-    await run2.processStream({ messages: messages2 }, streamConfig);
-
-    const finalMessages2 = run2.getRunMessages();
-    console.log(
-      `\n✓ Graph completed. Total messages: ${finalMessages2?.length ?? 0}`
-    );
-
-    const lastMsg2 = finalMessages2?.[finalMessages2.length - 1];
-    if (lastMsg2) {
-      const content =
-        typeof lastMsg2.content === 'string'
-          ? lastMsg2.content
-          : JSON.stringify(lastMsg2.content);
-      console.log(
-        `\n✓ Final response (first 500 chars):\n${content.slice(0, 500)}`
-      );
-    }
-
-    const lastActiveAgentId2 = run2.getLastActiveAgentId?.();
-    console.log(`\n✓ lastActiveAgentId: ${lastActiveAgentId2}`);
-
-    console.log(
-      '\n✅ Test 2 PASSED — Multi-hop handoff completed successfully'
-    );
-  } catch (err) {
-    console.error('\n❌ Test 2 FAILED:', (err as Error).message);
-    console.error((err as Error).stack);
-  }
-
-  console.log('\n\n=== All Tests Complete ===');
-}
-
-testAutonomousHandoff().catch(console.error);

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

@@ -1,278 +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, 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 } from '@/events';
-import { getLLMConfig } from '@/utils/llmConfig';
-import { GraphEvents, Providers } from '@/common';
-import { Run } from '@/run';
-
-const conversationHistory: BaseMessage[] = [];
-
-/**
- * Test multi-turn handoff between a coordinator and a specialist
- */
-async function testHandoffPreamble(): Promise<void> {
-  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: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
-      ): void => {
-        const runStep = data as t.RunStep;
-        if (runStep.agentId) {
-          currentAgent = runStep.agentId;
-          console.log(`\n[Agent: ${currentAgent}] Processing...`);
-        }
-        aggregateContent({ event, data: 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.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 => {
-        const toolData = data as { name?: string };
-        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: t.AgentInputs[] = [
-    {
-      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: t.GraphEdge[] = [
-    {
-      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: t.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: Partial<RunnableConfig> & {
-    version: 'v1' | 'v2';
-    streamMode: string;
-  } = {
-    configurable: {
-      thread_id: 'handoff-test-conversation-1',
-    },
-    streamMode: 'values',
-    version: 'v2' as const,
-  };
-
-  /** 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);
-});