@illuma-ai/agents 1.1.21 → 1.1.23

package/src/run.ts

@@ -1,7 +1,7 @@
 // src/run.ts
 import './instrumentation';
 import { ObservabilityCallbackHandler } from '@illuma-ai/observability-langchain';
-import { Command } from '@langchain/langgraph';
+import { Command, isGraphInterrupt } from '@langchain/langgraph';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';
@@ -349,20 +349,29 @@ export class Run<_T extends t.BaseGraphState> {
       ignoreCustomEvent: true,
     });
 
-    for await (const event of stream) {
-      const { data, metadata, ...info } = event;
+    try {
+      for await (const event of stream) {
+        const { data, metadata, ...info } = event;
 
-      const eventName: t.EventName = info.event;
+        const eventName: t.EventName = info.event;
 
-      /** Skip custom events as they're handled by our callback */
-      if (eventName === GraphEvents.ON_CUSTOM_EVENT) {
-        continue;
-      }
+        /** Skip custom events as they're handled by our callback */
+        if (eventName === GraphEvents.ON_CUSTOM_EVENT) {
+          continue;
+        }
 
-      const handler = this.handlerRegistry?.getHandler(eventName);
-      if (handler) {
-        await handler.handle(eventName, data, metadata, this.Graph);
+        const handler = this.handlerRegistry?.getHandler(eventName);
+        if (handler) {
+          await handler.handle(eventName, data, metadata, this.Graph);
+        }
+      }
+    } catch (e) {
+      // GraphInterrupt is expected when interrupt() fires (HITL approval flow).
+      // Exit gracefully so the host can check hasInterrupts() and resume.
+      if (isGraphInterrupt(e)) {
+        return undefined;
       }
+      throw e;
     }
 
     /**

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

@@ -0,0 +1,231 @@
+/**
+ * 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';
+config({ path: resolve(process.cwd(), '..', 'ranger', '.env'), 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/utils/llm.ts

@@ -24,3 +24,4 @@ export function isGoogleLike(provider?: string | Providers): boolean {
     provider
   );
 }
+