@illuma-ai/agents 1.0.89 → 1.0.93

package/src/scripts/poc-multi-agent-comprehensive.ts

@@ -0,0 +1,1222 @@
+/**
+ * Comprehensive Multi-Agent POC — All Combinations
+ *
+ * Tests every combination of edge type (handoff vs direct/sequential) and
+ * tool usage (none, single, multiple) end-to-end with Bedrock.
+ *
+ *   S1: Handoff — No tools
+ *   S2: Handoff — Single tool call
+ *   S3: Handoff — Multiple tool calls (3 tools)
+ *   S4: Sequential (direct edges) — No tools
+ *   S5: Sequential — Single tool per agent
+ *   S6: Sequential — Multiple tools per agent
+ *   S7: Hybrid (direct + handoff) — Mixed tools
+ *
+ * Usage:
+ *   npx tsx --tsconfig tsconfig.json -r tsconfig-paths/register src/scripts/poc-multi-agent-comprehensive.ts
+ */
+import { config } from 'dotenv';
+config();
+
+import {
+  HumanMessage,
+  BaseMessage,
+  getBufferString,
+} from '@langchain/core/messages';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+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';
+
+/* ------------------------------------------------------------------ */
+/*  Shared helpers                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Bedrock client options reused across all agents */
+const bedrockOptions: t.ClientOptions = {
+  region: process.env.BEDROCK_AWS_DEFAULT_REGION ?? 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.BEDROCK_AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.BEDROCK_AWS_SECRET_ACCESS_KEY!,
+  },
+  model: 'us.anthropic.claude-3-5-haiku-20241022-v1:0',
+};
+
+/** Create standard event handlers for observability */
+function createHandlers(label: string) {
+  const { contentParts, aggregateContent, stepMap } = createContentAggregator();
+
+  let currentAgent = '';
+
+  const handlers: Record<string, t.EventHandler> = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: {
+      handle: (
+        event: string,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>,
+        graph?: unknown
+      ): void => {
+        const chunk = data.chunk as Record<string, unknown> | undefined;
+        if (!chunk) return;
+        const content = chunk.content;
+        if (typeof content === 'string' && content) {
+          process.stdout.write(content);
+        } else if (Array.isArray(content)) {
+          for (const block of content) {
+            if (
+              typeof block === 'object' &&
+              block !== null &&
+              'type' in block &&
+              block.type === 'text' &&
+              'text' in block &&
+              typeof block.text === 'string'
+            ) {
+              process.stdout.write(block.text);
+            }
+          }
+        }
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        const runStepData = data as Record<string, unknown>;
+        const name =
+          typeof runStepData?.name === 'string' ? runStepData.name : undefined;
+        if (name && name !== currentAgent) {
+          currentAgent = name;
+          console.log(`\n\n>>> [${label}] Agent "${currentAgent}" starting...`);
+        }
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        const runStepData = data as Record<string, unknown>;
+        const name =
+          typeof runStepData?.name === 'string' ? runStepData.name : undefined;
+        if (name) {
+          console.log(`\n<<< [${label}] Agent "${name}" completed`);
+        }
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  return { handlers, contentParts, stepMap };
+}
+
+function printHeader(title: string) {
+  console.log('\n' + '='.repeat(80));
+  console.log(`  ${title}`);
+  console.log('='.repeat(80));
+}
+
+function printResult(label: string, success: boolean, details?: string) {
+  const icon = success ? '[PASS]' : '[FAIL]';
+  console.log(`\n${icon} ${label}`);
+  if (details) console.log(`  ${details}`);
+}
+
+/** Helper to build a default agent config */
+function agent(
+  agentId: string,
+  name: string,
+  instructions: string,
+  extras?: Partial<t.AgentInputs>
+): t.AgentInputs {
+  return {
+    agentId,
+    name,
+    provider: Providers.BEDROCK,
+    clientOptions: bedrockOptions,
+    instructions,
+    maxContextTokens: 8000,
+    ...extras,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Mock Tools                                                         */
+/* ------------------------------------------------------------------ */
+
+const getWeatherTool = new DynamicStructuredTool({
+  name: 'get_weather',
+  description:
+    'Get the current weather for a city. Returns temperature in Fahrenheit and conditions.',
+  schema: z.object({
+    city: z.string().describe('The city name'),
+  }),
+  func: async ({ city }) => {
+    const temps: Record<string, number> = {
+      boston: 45,
+      miami: 82,
+      'new york': 55,
+      'los angeles': 72,
+      chicago: 40,
+      london: 50,
+      tokyo: 60,
+      paris: 55,
+      sydney: 75,
+    };
+    const temp = temps[city.toLowerCase()] ?? 65;
+    return JSON.stringify({
+      city,
+      temperature: temp,
+      unit: 'F',
+      condition: temp > 70 ? 'Sunny' : temp > 50 ? 'Partly Cloudy' : 'Cold',
+    });
+  },
+});
+
+const getStockPriceTool = new DynamicStructuredTool({
+  name: 'get_stock_price',
+  description: 'Get the current stock price for a ticker symbol.',
+  schema: z.object({
+    ticker: z.string().describe('Stock ticker symbol (e.g. AAPL, GOOGL)'),
+  }),
+  func: async ({ ticker }) => {
+    const prices: Record<string, number> = {
+      AAPL: 178.5,
+      GOOGL: 141.2,
+      MSFT: 378.9,
+      AMZN: 185.6,
+      TSLA: 245.3,
+      META: 505.75,
+      NVDA: 875.4,
+    };
+    const price = prices[ticker.toUpperCase()] ?? 100.0;
+    const change = (Math.random() * 6 - 3).toFixed(2);
+    return JSON.stringify({
+      ticker: ticker.toUpperCase(),
+      price,
+      change: parseFloat(change),
+      currency: 'USD',
+    });
+  },
+});
+
+const searchDatabaseTool = new DynamicStructuredTool({
+  name: 'search_database',
+  description:
+    'Search the company database for employee or project information.',
+  schema: z.object({
+    query: z.string().describe('Search query'),
+    category: z
+      .enum(['employees', 'projects', 'departments'])
+      .describe('Category to search'),
+  }),
+  func: async ({ query, category }) => {
+    const results: Record<string, Record<string, string[]>> = {
+      employees: {
+        engineering: [
+          'Alice Chen (Senior Engineer)',
+          'Bob Kumar (Tech Lead)',
+          'Carol Smith (Staff Engineer)',
+        ],
+        marketing: ['Dan Lee (VP Marketing)', 'Eva Brown (Content Manager)'],
+      },
+      projects: {
+        active: [
+          'Project Phoenix (AI Platform)',
+          'Project Atlas (Data Migration)',
+          'Project Nexus (API Gateway)',
+        ],
+        completed: ['Project Omega (Auth System)', 'Project Delta (Dashboard)'],
+      },
+      departments: {
+        all: [
+          'Engineering (45 people)',
+          'Marketing (12 people)',
+          'Sales (20 people)',
+          'Operations (8 people)',
+        ],
+      },
+    };
+    const catResults = results[category] ?? {};
+    const matchingValues = Object.values(catResults)
+      .flat()
+      .filter((v) => v.toLowerCase().includes(query.toLowerCase()));
+    return JSON.stringify({
+      category,
+      query,
+      results:
+        matchingValues.length > 0
+          ? matchingValues
+          : Object.values(catResults).flat().slice(0, 3),
+      totalMatches: matchingValues.length || 3,
+    });
+  },
+});
+
+const translateTextTool = new DynamicStructuredTool({
+  name: 'translate_text',
+  description: 'Translate text from one language to another.',
+  schema: z.object({
+    text: z.string().describe('Text to translate'),
+    targetLanguage: z
+      .string()
+      .describe('Target language (e.g. Spanish, French, Japanese)'),
+  }),
+  func: async ({ text, targetLanguage }) => {
+    const translations: Record<string, string> = {
+      spanish: `[ES] ${text} (traducción simulada)`,
+      french: `[FR] ${text} (traduction simulée)`,
+      japanese: `[JA] ${text} (模擬翻訳)`,
+      german: `[DE] ${text} (simulierte Übersetzung)`,
+    };
+    return JSON.stringify({
+      original: text,
+      translated:
+        translations[targetLanguage.toLowerCase()] ??
+        `[${targetLanguage}] ${text} (simulated)`,
+      targetLanguage,
+    });
+  },
+});
+
+const getTimeTool = new DynamicStructuredTool({
+  name: 'get_time',
+  description: 'Get the current time in a specific timezone.',
+  schema: z.object({
+    timezone: z.string().describe('Timezone (e.g. EST, PST, UTC, JST)'),
+  }),
+  func: async ({ timezone }) => {
+    const offsets: Record<string, number> = {
+      EST: -5,
+      PST: -8,
+      CST: -6,
+      MST: -7,
+      UTC: 0,
+      GMT: 0,
+      JST: 9,
+      CET: 1,
+      IST: 5.5,
+      AEST: 11,
+    };
+    const offset = offsets[timezone.toUpperCase()] ?? 0;
+    const now = new Date();
+    const utcHour = now.getUTCHours();
+    const localHour = (utcHour + offset + 24) % 24;
+    const mins = now.getUTCMinutes().toString().padStart(2, '0');
+    return JSON.stringify({
+      timezone: timezone.toUpperCase(),
+      time: `${Math.floor(localHour)}:${mins}`,
+      date: now.toISOString().split('T')[0],
+    });
+  },
+});
+
+const sentimentAnalysisTool = new DynamicStructuredTool({
+  name: 'analyze_sentiment',
+  description:
+    'Analyze the sentiment of a piece of text. Returns positive, negative, or neutral with a confidence score.',
+  schema: z.object({
+    text: z.string().describe('Text to analyze for sentiment'),
+  }),
+  func: async ({ text }) => {
+    const words = text.toLowerCase().split(/\s+/);
+    const positive = [
+      'good',
+      'great',
+      'excellent',
+      'amazing',
+      'love',
+      'best',
+      'happy',
+      'wonderful',
+      'fantastic',
+    ];
+    const negative = [
+      'bad',
+      'terrible',
+      'awful',
+      'hate',
+      'worst',
+      'poor',
+      'disappointed',
+      'horrible',
+    ];
+    const posCount = words.filter((w) => positive.includes(w)).length;
+    const negCount = words.filter((w) => negative.includes(w)).length;
+    const sentiment =
+      posCount > negCount
+        ? 'positive'
+        : negCount > posCount
+          ? 'negative'
+          : 'neutral';
+    const confidence = Math.min(
+      0.95,
+      0.6 + Math.abs(posCount - negCount) * 0.1
+    );
+    return JSON.stringify({ sentiment, confidence, wordCount: words.length });
+  },
+});
+
+/* ================================================================== */
+/*  S1: Handoff — No Tools                                             */
+/*  flight_assistant -> hotel_assistant (pure conversation handoff)     */
+/* ================================================================== */
+async function s1_handoff_noTools(): Promise<boolean> {
+  printHeader('S1: HANDOFF — NO TOOLS');
+  console.log('  flight_assistant -> hotel_assistant');
+  console.log('  Pure conversation handoff, no tools involved\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'flight_assistant',
+      'Flight Assistant',
+      `You are a flight booking assistant. Help users with flight-related queries.
+When the user also needs hotel assistance, first briefly address the flight part (2-3 sentences),
+then use the handoff tool to transfer to the hotel assistant.
+Do NOT try to answer hotel questions yourself.`
+    ),
+    agent(
+      'hotel_assistant',
+      'Hotel Assistant',
+      `You are a hotel booking assistant. Help users with hotel-related queries.
+Provide your hotel recommendations (2-3 sentences) and complete the conversation.
+Do NOT transfer back to the flight assistant.`
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'flight_assistant',
+      to: 'hotel_assistant',
+      description:
+        'Transfer to hotel assistant when user needs hotel booking help',
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S1');
+
+  try {
+    const run = await Run.create({
+      runId: `s1-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'I need a flight from Boston to Miami, and also need a hotel near South Beach for 3 nights.'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's1' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const lastAgent = run.getLastActiveAgentId?.();
+
+    console.log(`\n\n--- S1 Results ---`);
+    console.log(`  AI messages: ${aiCount}, Last agent: ${lastAgent}`);
+
+    const success = aiCount >= 2 && lastAgent === 'hotel_assistant';
+    printResult(
+      'S1: Handoff — No Tools',
+      success,
+      success
+        ? `Both agents participated (${aiCount} AI msgs), handoff to hotel confirmed`
+        : `Expected 2+ AI msgs & hotel_assistant last, got ${aiCount} msgs & ${lastAgent}`
+    );
+    return success;
+  } catch (error) {
+    console.error('S1 error:', error);
+    printResult('S1: Handoff — No Tools', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S2: Handoff — Single Tool                                          */
+/*  weather_agent (get_weather) -> activity_advisor                     */
+/* ================================================================== */
+async function s2_handoff_singleTool(): Promise<boolean> {
+  printHeader('S2: HANDOFF — SINGLE TOOL');
+  console.log('  weather_agent [get_weather] -> activity_advisor');
+  console.log('  Agent calls one tool, then hands off\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'weather_agent',
+      'Weather Agent',
+      `You are a Weather Agent. When the user asks about weather:
+1. Use the get_weather tool to get the data for the requested city
+2. Briefly report the temperature and condition (1 sentence)
+3. Then IMMEDIATELY hand off to the activity advisor
+You MUST hand off after reporting the weather. Do NOT suggest activities yourself.`,
+      { tools: [getWeatherTool], description: 'Gets weather data using tools' }
+    ),
+    agent(
+      'activity_advisor',
+      'Activity Advisor',
+      `You are an Activity Advisor. Based on the weather information from the previous agent:
+1. Suggest 2-3 activities suited for the conditions
+2. Recommend what to wear or pack
+Keep it brief (2-3 sentences).`,
+      { description: 'Recommends activities based on weather' }
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'weather_agent',
+      to: 'activity_advisor',
+      description: 'Transfer to activity advisor after getting weather data',
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S2');
+
+  try {
+    const run = await Run.create({
+      runId: `s2-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'What is the weather like in Miami? What activities should I plan?'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's2' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const toolCount =
+      runMessages?.filter((m) => m._getType() === 'tool').length ?? 0;
+    const lastAgent = run.getLastActiveAgentId?.();
+
+    console.log(`\n\n--- S2 Results ---`);
+    console.log(
+      `  AI messages: ${aiCount}, Tool messages: ${toolCount}, Last agent: ${lastAgent}`
+    );
+
+    const success = aiCount >= 2 && toolCount >= 1;
+    printResult(
+      'S2: Handoff — Single Tool',
+      success,
+      `Tool used: ${toolCount >= 1}, Handoff: ${lastAgent === 'activity_advisor'}, AI msgs: ${aiCount}`
+    );
+    return success;
+  } catch (error) {
+    console.error('S2 error:', error);
+    printResult('S2: Handoff — Single Tool', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S3: Handoff — Multiple Tools                                       */
+/*  research_agent [weather + stock + time] -> report_agent             */
+/* ================================================================== */
+async function s3_handoff_multipleTools(): Promise<boolean> {
+  printHeader('S3: HANDOFF — MULTIPLE TOOLS (3 tools)');
+  console.log(
+    '  research_agent [get_weather, get_stock_price, get_time] -> report_agent'
+  );
+  console.log('  Agent calls multiple tools, then hands off\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'research_agent',
+      'Research Agent',
+      `You are a Research Agent with three tools: get_weather, get_stock_price, and get_time.
+When the user asks for a briefing:
+1. Use get_weather to check weather in the requested city
+2. Use get_stock_price to check the requested stock
+3. Use get_time to check the time in the requested timezone
+After gathering ALL data from all three tools, briefly summarize your findings (2-3 sentences).
+Then IMMEDIATELY hand off to the report agent. Do NOT write the full report yourself.`,
+      {
+        tools: [getWeatherTool, getStockPriceTool, getTimeTool],
+        description: 'Gathers data from multiple tools',
+      }
+    ),
+    agent(
+      'report_agent',
+      'Report Agent',
+      `You are a Report Agent. Based on the research data provided:
+1. Create a formatted executive morning briefing
+2. Include weather, market, and time sections
+3. End with a brief recommendation for the day
+Keep it to 4-6 sentences total.`,
+      { description: 'Creates formatted reports from gathered data' }
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'research_agent',
+      to: 'report_agent',
+      description:
+        'Transfer to report agent after gathering all research data to create a formatted report',
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S3');
+
+  try {
+    const run = await Run.create({
+      runId: `s3-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'Give me a morning briefing: weather in New York, AAPL stock price, and current time in EST.'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's3' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const toolCount =
+      runMessages?.filter((m) => m._getType() === 'tool').length ?? 0;
+    const lastAgent = run.getLastActiveAgentId?.();
+
+    console.log(`\n\n--- S3 Results ---`);
+    console.log(
+      `  AI messages: ${aiCount}, Tool messages: ${toolCount}, Last agent: ${lastAgent}`
+    );
+
+    /** Expect at least 3 tool calls (weather + stock + time) */
+    const success = aiCount >= 2 && toolCount >= 3;
+    printResult(
+      'S3: Handoff — Multiple Tools',
+      success,
+      `Tools called: ${toolCount} (expected ≥3), Handoff: ${lastAgent === 'report_agent'}, AI msgs: ${aiCount}`
+    );
+    return success;
+  } catch (error) {
+    console.error('S3 error:', error);
+    printResult('S3: Handoff — Multiple Tools', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S4: Sequential (Direct Edges) — No Tools                           */
+/*  researcher -> analyst -> summarizer (sim-style DAG)                */
+/* ================================================================== */
+async function s4_sequential_noTools(): Promise<boolean> {
+  printHeader('S4: SEQUENTIAL (DIRECT) — NO TOOLS');
+  console.log('  researcher -> analyst -> summarizer');
+  console.log('  Each agent receives previous outputs as context, no tools\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'researcher',
+      'Researcher',
+      `You are a Research Agent. Your task:
+1. Analyze the user's question
+2. List 3-4 key facts or considerations
+Keep it to 3-4 bullet points. Start with "RESEARCH:"`
+    ),
+    agent(
+      'analyst',
+      'Analyst',
+      `You are an Analysis Agent. Your task:
+1. Read the research findings from the previous agent
+2. Identify patterns, risks, and opportunities
+3. Add deeper analytical insights
+Keep it to 3-4 bullet points. Start with "ANALYSIS:"`
+    ),
+    agent(
+      'summarizer',
+      'Summarizer',
+      `You are a Summary Agent. Your task:
+1. Synthesize the research AND analysis from previous agents
+2. Create a cohesive 2-3 sentence executive summary
+3. End with one key recommendation
+Start with "SUMMARY:" and end with "RECOMMENDATION:"`
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'researcher',
+      to: 'analyst',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here are the research findings. Analyze them and provide insights:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+    {
+      from: 'analyst',
+      to: 'summarizer',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here are the combined research and analysis. Synthesize into a final summary:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S4');
+
+  try {
+    const run = await Run.create({
+      runId: `s4-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'What are the key considerations for migrating a monolithic application to microservices?'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's4' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiMessages = runMessages?.filter((m) => m._getType() === 'ai') ?? [];
+
+    console.log(`\n\n--- S4 Results ---`);
+    console.log(`  AI messages: ${aiMessages.length}`);
+    for (let i = 0; i < aiMessages.length; i++) {
+      const name = ['researcher', 'analyst', 'summarizer'][i] ?? `agent_${i}`;
+      const content =
+        typeof aiMessages[i].content === 'string'
+          ? aiMessages[i].content
+          : JSON.stringify(aiMessages[i].content);
+      console.log(`  ${name}: ${(content as string).slice(0, 80)}...`);
+    }
+
+    const success = aiMessages.length === 3;
+    printResult(
+      'S4: Sequential — No Tools',
+      success,
+      success
+        ? `All 3 agents produced output sequentially`
+        : `Expected 3 AI messages, got ${aiMessages.length}`
+    );
+    return success;
+  } catch (error) {
+    console.error('S4 error:', error);
+    printResult('S4: Sequential — No Tools', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S5: Sequential (Direct Edges) — Single Tool Per Agent              */
+/*  data_collector [search_database] -> translator [translate_text]     */
+/*       -> reviewer (no tool)                                         */
+/* ================================================================== */
+async function s5_sequential_singleTool(): Promise<boolean> {
+  printHeader('S5: SEQUENTIAL (DIRECT) — SINGLE TOOL PER AGENT');
+  console.log(
+    '  data_collector [search_database] -> translator [translate_text] -> reviewer'
+  );
+  console.log('  Each agent has one tool, output flows sequentially\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'data_collector',
+      'Data Collector',
+      `You are a Data Collector Agent. When given a query:
+1. Use the search_database tool to find relevant information
+2. Present the search results in a clear, organized format (3-4 bullet points)
+Start with "DATA COLLECTED:"`,
+      {
+        tools: [searchDatabaseTool],
+        description: 'Searches database for information',
+      }
+    ),
+    agent(
+      'translator',
+      'Translator',
+      `You are a Translator Agent. When you receive data from the previous agent:
+1. Use the translate_text tool to translate the KEY findings to the requested language
+2. Present both original and translated versions
+Keep it brief. Start with "TRANSLATED:"`,
+      {
+        tools: [translateTextTool],
+        description: 'Translates text between languages',
+      }
+    ),
+    agent(
+      'reviewer',
+      'Quality Reviewer',
+      `You are a Quality Reviewer. Review the collected and translated data:
+1. Confirm data accuracy and translation quality
+2. Note any issues
+3. Give a quality score (1-10)
+Start with "REVIEW:" and keep it to 3-4 lines.`
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'data_collector',
+      to: 'translator',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here is the collected data. Translate the key findings to Spanish:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+    {
+      from: 'translator',
+      to: 'reviewer',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here is the collected and translated data. Review it for quality:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S5');
+
+  try {
+    const run = await Run.create({
+      runId: `s5-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'Search for engineering employees and translate the key findings to Spanish.'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's5' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const toolCount =
+      runMessages?.filter((m) => m._getType() === 'tool').length ?? 0;
+
+    console.log(`\n\n--- S5 Results ---`);
+    console.log(`  AI messages: ${aiCount}, Tool messages: ${toolCount}`);
+
+    /** Expect at least 2 tool calls (search + translate) across the chain */
+    const success = aiCount >= 3 && toolCount >= 2;
+    printResult(
+      'S5: Sequential — Single Tool',
+      success,
+      `AI msgs: ${aiCount} (expected 3), Tool calls: ${toolCount} (expected ≥2)`
+    );
+    return success;
+  } catch (error) {
+    console.error('S5 error:', error);
+    printResult('S5: Sequential — Single Tool', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S6: Sequential (Direct Edges) — Multiple Tools Per Agent           */
+/*  intel_gatherer [weather+stock+time] -> analyst [sentiment+search]  */
+/*       -> presenter (no tools)                                       */
+/* ================================================================== */
+async function s6_sequential_multipleTools(): Promise<boolean> {
+  printHeader('S6: SEQUENTIAL (DIRECT) — MULTIPLE TOOLS PER AGENT');
+  console.log(
+    '  intel_gatherer [weather, stock, time] -> analyst [sentiment, search_db] -> presenter'
+  );
+  console.log('  Agents have 2-3 tools each, output flows sequentially\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'intel_gatherer',
+      'Intelligence Gatherer',
+      `You are an Intelligence Gatherer Agent with three tools: get_weather, get_stock_price, and get_time.
+For the morning intelligence report:
+1. Use get_weather to check weather in Tokyo
+2. Use get_stock_price to check NVDA stock
+3. Use get_time to check current time in JST
+Present all gathered data clearly. Start with "INTEL GATHERED:"`,
+      {
+        tools: [getWeatherTool, getStockPriceTool, getTimeTool],
+        description: 'Gathers intelligence from multiple data sources',
+      }
+    ),
+    agent(
+      'market_analyst',
+      'Market Analyst',
+      `You are a Market Analyst Agent with two tools: analyze_sentiment and search_database.
+Based on the intelligence gathered:
+1. Use analyze_sentiment on a summary of the market conditions described by the previous agent
+2. Use search_database to find relevant projects in the "projects" category related to "AI"
+3. Combine insights into a brief market analysis
+Start with "MARKET ANALYSIS:"`,
+      {
+        tools: [sentimentAnalysisTool, searchDatabaseTool],
+        description: 'Analyzes market sentiment and cross-references data',
+      }
+    ),
+    agent(
+      'presenter',
+      'Executive Presenter',
+      `You are an Executive Presenter Agent. Create a polished executive summary from the intelligence and analysis:
+1. Lead with the most important insight
+2. Include key metrics (weather, market, time)
+3. End with an actionable recommendation
+Format as a brief executive memo (4-5 sentences). Start with "EXECUTIVE SUMMARY:"`
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    {
+      from: 'intel_gatherer',
+      to: 'market_analyst',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here is the gathered intelligence. Analyze the market sentiment and cross-reference with our database:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+    {
+      from: 'market_analyst',
+      to: 'presenter',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here is the intelligence and market analysis. Create a polished executive summary:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S6');
+
+  try {
+    const run = await Run.create({
+      runId: `s6-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'Create a morning intelligence briefing: check Tokyo weather, NVDA stock, and JST time. Then analyze market sentiment and find relevant AI projects.'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's6' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const toolCount =
+      runMessages?.filter((m) => m._getType() === 'tool').length ?? 0;
+
+    console.log(`\n\n--- S6 Results ---`);
+    console.log(`  AI messages: ${aiCount}, Tool messages: ${toolCount}`);
+
+    /** Expect at least 5 tool calls (3 from gatherer + 2 from analyst) */
+    const success = aiCount >= 3 && toolCount >= 5;
+    printResult(
+      'S6: Sequential — Multiple Tools',
+      success,
+      `AI msgs: ${aiCount} (expected 3+), Tool calls: ${toolCount} (expected ≥5)`
+    );
+    return success;
+  } catch (error) {
+    console.error('S6 error:', error);
+    printResult('S6: Sequential — Multiple Tools', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  S7: Hybrid (Direct + Handoff) — Mixed Tools                        */
+/*  planner --(direct)--> researcher [weather+stock] --(handoff)-->    */
+/*    writer OR analyst [sentiment]                                    */
+/*  Direct sequential flow + dynamic handoff with tools                */
+/* ================================================================== */
+async function s7_hybrid_mixedTools(): Promise<boolean> {
+  printHeader('S7: HYBRID (DIRECT + HANDOFF) — MIXED TOOLS');
+  console.log('  planner --(direct)--> researcher [weather, stock]');
+  console.log('    --(handoff)--> writer (no tools) OR analyst [sentiment]');
+  console.log('  Combines direct sequential + dynamic handoff + tools\n');
+
+  const agents: t.AgentInputs[] = [
+    agent(
+      'planner',
+      'Content Planner',
+      `You are a Content Planner. Given a topic:
+1. Create a brief 3-point outline for a market report
+2. Specify what data needs to be gathered (weather and stock)
+3. Note the target audience
+Keep it to 3-4 lines. Start with "PLAN:"`,
+      { description: 'Plans content structure and outlines' }
+    ),
+    agent(
+      'researcher',
+      'Data Researcher',
+      `You are a Data Researcher with get_weather and get_stock_price tools.
+Based on the content plan:
+1. Use get_weather to get weather for the city mentioned in the plan (default: Los Angeles)
+2. Use get_stock_price to get the stock price mentioned in the plan (default: GOOGL)
+3. Briefly summarize your data findings (2-3 sentences)
+Then transfer to the writer to create the full report.
+IMPORTANT: After gathering data, you MUST use the transfer tool to send to the writer.
+Start with "RESEARCH DATA:"`,
+      {
+        tools: [getWeatherTool, getStockPriceTool],
+        description:
+          'Gathers data using research tools, can route to writer or analyst',
+      }
+    ),
+    agent(
+      'writer',
+      'Report Writer',
+      `You are a Report Writer. Based on the plan and research data:
+1. Write a brief market report (3-4 sentences)
+2. Include specific data points from the research
+3. Add a conclusion
+Start with "REPORT:" and keep it professional.`,
+      { description: 'Writes formatted reports from research data' }
+    ),
+    agent(
+      'analyst',
+      'Sentiment Analyst',
+      `You are a Sentiment Analyst with the analyze_sentiment tool.
+If you receive research data:
+1. Use analyze_sentiment on a summary of the market conditions
+2. Provide your sentiment assessment
+3. Give a market outlook (bullish/bearish/neutral)
+Start with "SENTIMENT ANALYSIS:"`,
+      {
+        tools: [sentimentAnalysisTool],
+        description: 'Analyzes sentiment of market data',
+      }
+    ),
+  ];
+
+  const edges: t.GraphEdge[] = [
+    /** Direct: planner always flows to researcher */
+    {
+      from: 'planner',
+      to: 'researcher',
+      edgeType: 'direct',
+      prompt: (messages: BaseMessage[], startIndex: number) => {
+        const buffer = getBufferString(messages.slice(startIndex));
+        return `Here is the content plan. Gather the required data:\n\n${buffer}`;
+      },
+      excludeResults: true,
+    },
+    /** Handoff: researcher dynamically chooses writer or analyst */
+    {
+      from: 'researcher',
+      to: 'writer',
+      description:
+        'Transfer to the report writer to create a formatted market report from the gathered data',
+    },
+    {
+      from: 'researcher',
+      to: 'analyst',
+      description:
+        'Transfer to the sentiment analyst for deeper market sentiment analysis',
+    },
+  ];
+
+  const { handlers, contentParts } = createHandlers('S7');
+
+  try {
+    const run = await Run.create({
+      runId: `s7-${Date.now()}`,
+      graphConfig: { type: 'multi-agent', agents, edges },
+      customHandlers: handlers,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    await run.processStream(
+      {
+        messages: [
+          new HumanMessage(
+            'Create a market report: plan the structure, gather weather for Los Angeles and GOOGL stock data, then write the full report.'
+          ),
+        ],
+      },
+      { configurable: { thread_id: 's7' }, version: 'v2' as const }
+    );
+
+    const runMessages = run.getRunMessages();
+    const aiCount =
+      runMessages?.filter((m) => m._getType() === 'ai').length ?? 0;
+    const toolCount =
+      runMessages?.filter((m) => m._getType() === 'tool').length ?? 0;
+    const lastAgent = run.getLastActiveAgentId?.();
+
+    console.log(`\n\n--- S7 Results ---`);
+    console.log(
+      `  AI messages: ${aiCount}, Tool messages: ${toolCount}, Last agent: ${lastAgent}`
+    );
+
+    /** Expect: planner (1 AI) + researcher (1+ AI with 2+ tools) + writer or analyst (1 AI) = 3+ AI, 2+ tools */
+    const success = aiCount >= 3 && toolCount >= 2;
+    printResult(
+      'S7: Hybrid — Mixed Tools',
+      success,
+      `AI msgs: ${aiCount} (expected 3+), Tools: ${toolCount} (expected ≥2), ` +
+        `Last: ${lastAgent}, Direct (planner→researcher) + handoff (researcher→${lastAgent}) verified`
+    );
+    return success;
+  } catch (error) {
+    console.error('S7 error:', error);
+    printResult('S7: Hybrid — Mixed Tools', false, String(error));
+    return false;
+  }
+}
+
+/* ================================================================== */
+/*  Main Runner                                                        */
+/* ================================================================== */
+async function main() {
+  console.log('\n');
+  console.log('*'.repeat(80));
+  console.log('*  ILLUMA AGENTS — COMPREHENSIVE MULTI-AGENT POC');
+  console.log('*  Provider: AWS Bedrock (Claude 3.5 Haiku)');
+  console.log('*');
+  console.log('*  HANDOFF scenarios:');
+  console.log(
+    '*    S1: No tools          S2: Single tool       S3: Multiple tools'
+  );
+  console.log('*  SEQUENTIAL scenarios:');
+  console.log(
+    '*    S4: No tools          S5: Single tool       S6: Multiple tools'
+  );
+  console.log('*  HYBRID:');
+  console.log('*    S7: Direct + Handoff + Mixed tools');
+  console.log('*'.repeat(80));
+
+  const results: Record<string, boolean> = {};
+
+  /** Run all scenarios sequentially for clear output */
+  results['S1: Handoff — No Tools'] = await s1_handoff_noTools();
+  results['S2: Handoff — Single Tool'] = await s2_handoff_singleTool();
+  results['S3: Handoff — Multiple Tools (3)'] =
+    await s3_handoff_multipleTools();
+  results['S4: Sequential — No Tools'] = await s4_sequential_noTools();
+  results['S5: Sequential — Single Tool'] = await s5_sequential_singleTool();
+  results['S6: Sequential — Multiple Tools (2-3)'] =
+    await s6_sequential_multipleTools();
+  results['S7: Hybrid — Direct + Handoff + Tools'] =
+    await s7_hybrid_mixedTools();
+
+  /** Final summary */
+  printHeader('POC RESULTS SUMMARY');
+
+  const entries = Object.entries(results);
+  let passCount = 0;
+
+  console.log('\n  HANDOFF:');
+  for (const [name, passed] of entries.filter(
+    ([n]) => n.startsWith('S1') || n.startsWith('S2') || n.startsWith('S3')
+  )) {
+    console.log(`    ${passed ? '[PASS]' : '[FAIL]'} ${name}`);
+    if (passed) passCount++;
+  }
+
+  console.log('\n  SEQUENTIAL:');
+  for (const [name, passed] of entries.filter(
+    ([n]) => n.startsWith('S4') || n.startsWith('S5') || n.startsWith('S6')
+  )) {
+    console.log(`    ${passed ? '[PASS]' : '[FAIL]'} ${name}`);
+    if (passed) passCount++;
+  }
+
+  console.log('\n  HYBRID:');
+  for (const [name, passed] of entries.filter(([n]) => n.startsWith('S7'))) {
+    console.log(`    ${passed ? '[PASS]' : '[FAIL]'} ${name}`);
+    if (passed) passCount++;
+  }
+
+  console.log(`\n  ${passCount}/${entries.length} scenarios passed`);
+
+  if (passCount === entries.length) {
+    console.log('\n  All scenarios passed! Multi-agent system fully verified.');
+  } else {
+    console.log('\n  Some scenarios failed. Check output above for details.');
+  }
+
+  console.log('\n' + '='.repeat(80));
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});