@illuma-ai/agents 1.1.20 → 1.1.22

package/src/graphs/__tests__/multi-agent-delegate.test.ts

@@ -206,3 +206,194 @@ describe('handoff tool naming', () => {
     expect(transferName).toBe('lc_transfer_to_test');
   });
 });
+
+// ---------------------------------------------------------------------------
+// prepareHandoffMessages
+// ---------------------------------------------------------------------------
+describe('prepareHandoffMessages', () => {
+  it('returns empty array for empty input', () => {
+    expect(MultiAgentGraph.prepareHandoffMessages([])).toEqual([]);
+  });
+
+  it('passes through plain HumanMessage and text-only AIMessage unchanged', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Hello'),
+      new AIMessage('Hi there'),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+    expect(result).toHaveLength(2);
+    expect(result[0].getType()).toBe('human');
+    expect(result[0].content).toBe('Hello');
+    expect(result[1].getType()).toBe('ai');
+    expect(result[1].content).toBe('Hi there');
+  });
+
+  it('strips orphaned tool_use blocks (no matching tool_result)', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Do something'),
+      new AIMessage({
+        content: 'Let me call a tool',
+        tool_calls: [
+          { name: 'lc_handoff_to_researcher', args: { instructions: 'research this' }, id: 'tc1', type: 'tool_call' },
+        ],
+      }),
+      // No ToolMessage for tc1 — it's orphaned
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+    expect(result).toHaveLength(2);
+    expect(result[0].content).toBe('Do something');
+    // AI message should be converted to text-only (no tool_calls)
+    expect(result[1].getType()).toBe('ai');
+    expect(result[1].content).toContain('Let me call a tool');
+    // Should NOT contain tool_calls
+    const aiMsg = result[1] as AIMessage;
+    expect(aiMsg.tool_calls ?? []).toHaveLength(0);
+  });
+
+  it('compacts paired tool_use/tool_result into text summaries', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Search for data'),
+      new AIMessage({
+        content: 'I will search for you',
+        tool_calls: [
+          { name: 'web_search', args: { query: 'test' }, id: 'tc1', type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({ content: 'Found 3 results about testing', tool_call_id: 'tc1', name: 'web_search' }),
+      new AIMessage('Based on the search, here is what I found.'),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+
+    // Should have: HumanMessage, compacted AIMessage (with tool summary), final AIMessage
+    expect(result).toHaveLength(3);
+
+    // ToolMessage should be removed
+    expect(result.every((m) => m.getType() !== 'tool')).toBe(true);
+
+    // Compacted AI message should contain tool summary
+    const compactedAI = result[1];
+    expect(compactedAI.content).toContain('I will search for you');
+    expect(compactedAI.content).toContain('web_search');
+    expect(compactedAI.content).toContain('Found 3 results');
+  });
+
+  it('removes ALL ToolMessages from output', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('task'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          { name: 'tool_a', args: {}, id: 'tc1', type: 'tool_call' },
+          { name: 'tool_b', args: {}, id: 'tc2', type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({ content: 'result a', tool_call_id: 'tc1', name: 'tool_a' }),
+      new ToolMessage({ content: 'result b', tool_call_id: 'tc2', name: 'tool_b' }),
+      new AIMessage('Final answer.'),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+
+    // Zero ToolMessages in output
+    const toolMsgs = result.filter((m) => m.getType() === 'tool');
+    expect(toolMsgs).toHaveLength(0);
+  });
+
+  it('handles multi-hop scenario: multiple tool interactions compacted', () => {
+    // Simulates: Orchestrator called researcher (handoff), got result,
+    // then called writer (handoff) — the writer should get clean messages
+    const messages: BaseMessage[] = [
+      new HumanMessage('Research and write a report'),
+      // Orchestrator's first tool call (handoff to researcher)
+      new AIMessage({
+        content: 'I will delegate to the researcher first.',
+        tool_calls: [
+          { name: 'lc_handoff_to_researcher', args: { instructions: 'research AI trends' }, id: 'h1', type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({ content: 'Research findings: AI adoption is growing rapidly...', tool_call_id: 'h1', name: 'lc_handoff_to_researcher' }),
+      // Orchestrator's response after getting research back
+      new AIMessage({
+        content: 'Now I will delegate to the writer.',
+        tool_calls: [
+          { name: 'lc_handoff_to_writer', args: { instructions: 'write report based on findings' }, id: 'h2', type: 'tool_call' },
+        ],
+      }),
+      // h2 is orphaned — writer hasn't returned yet (this is the current handoff)
+    ];
+
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+
+    // No ToolMessages
+    expect(result.filter((m) => m.getType() === 'tool')).toHaveLength(0);
+
+    // No tool_calls on any AI message
+    for (const msg of result) {
+      if (msg.getType() === 'ai') {
+        expect((msg as AIMessage).tool_calls ?? []).toHaveLength(0);
+      }
+    }
+
+    // Should have: HumanMessage + 2 compacted/cleaned AI messages
+    expect(result).toHaveLength(3);
+
+    // First AI message should have researcher tool summary (paired)
+    expect(result[1].content).toContain('lc_handoff_to_researcher');
+    expect(result[1].content).toContain('AI adoption');
+
+    // Second AI message should be text-only (orphaned tool_use stripped)
+    expect(result[2].content).toContain('Now I will delegate to the writer');
+  });
+
+  it('preserves message order', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Step 1'),
+      new AIMessage('Response 1'),
+      new HumanMessage('Step 2'),
+      new AIMessage('Response 2'),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+    expect(result).toHaveLength(4);
+    expect(result[0].content).toBe('Step 1');
+    expect(result[1].content).toBe('Response 1');
+    expect(result[2].content).toBe('Step 2');
+    expect(result[3].content).toBe('Response 2');
+  });
+
+  it('drops AI messages that have only tool_calls and no text content', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('Do it'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          { name: 'orphan_tool', args: {}, id: 'orp1', type: 'tool_call' },
+        ],
+      }),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+    // AI message with empty content + orphaned tool = nothing to keep
+    expect(result).toHaveLength(1);
+    expect(result[0].content).toBe('Do it');
+  });
+
+  it('handles AI messages with array content (text blocks)', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('task'),
+      new AIMessage({
+        content: [
+          { type: 'text', text: 'Part one.' },
+          { type: 'text', text: 'Part two.' },
+        ],
+        tool_calls: [
+          { name: 'some_tool', args: {}, id: 'tc1', type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({ content: 'tool output', tool_call_id: 'tc1', name: 'some_tool' }),
+    ];
+    const result = MultiAgentGraph.prepareHandoffMessages(messages);
+    expect(result).toHaveLength(2);
+    const aiContent = result[1].content as string;
+    expect(aiContent).toContain('Part one.');
+    expect(aiContent).toContain('Part two.');
+    expect(aiContent).toContain('some_tool');
+  });
+});

package/src/llm/bedrock/index.ts

@@ -167,6 +167,23 @@ export class IllumaBedrockConverse extends ChatBedrockConverse {
     const params = super.invocationParams(options);
 
     // Add cachePoint to tools array if promptCache is enabled and tools exist
+    /**
+     * Bedrock requires all toolSpec.description fields to be non-empty strings.
+     * Some tools (e.g., MCP-sourced or dynamically created) may have empty or
+     * missing descriptions. Patch them here to avoid Bedrock validation errors.
+     */
+    if (
+      params.toolConfig?.tools &&
+      Array.isArray(params.toolConfig.tools)
+    ) {
+      for (const t of params.toolConfig.tools) {
+        const spec = (t as { toolSpec?: { description?: string } }).toolSpec;
+        if (spec && (!spec.description || spec.description === '')) {
+          spec.description = spec.description || `Tool: ${(spec as { name?: string }).name ?? 'unknown'}`;
+        }
+      }
+    }
+
     // Only Claude models support cachePoint - check model name
     const modelId = this.model.toLowerCase();
     const isClaudeModel =

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);