@illuma-ai/agents 1.0.90 → 1.0.94

package/src/specs/agent-handoffs.test.js

@@ -0,0 +1,924 @@
+// src/specs/agent-handoffs.test.ts
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { HumanMessage, ToolMessage } from '@langchain/core/messages';
+import { Providers, Constants } from '@/common';
+import { Run } from '@/run';
+/**
+ * Helper to safely get tool name from tool object
+ */
+const getToolName = (tool) => {
+    return tool.name;
+};
+/**
+ * Helper to safely get tool description from tool object
+ */
+const getToolDescription = (tool) => {
+    return tool.description;
+};
+/**
+ * Helper to safely get tool schema from tool object
+ */
+const getToolSchema = (tool) => {
+    return tool.schema;
+};
+/**
+ * Helper to find tool by name
+ */
+const findToolByName = (tools, name) => {
+    return tools?.find((tool) => getToolName(tool) === name);
+};
+/**
+ * Test suite for Agent Handoffs feature
+ *
+ * Tests cover:
+ * - Basic handoff between two agents
+ * - Handoffs with custom descriptions
+ * - Handoffs with prompts and prompt keys
+ * - Sequential handoffs (A -> B -> C)
+ * - Bidirectional handoffs (A <-> B)
+ * - Multiple handoff options from single agent
+ * - Handoff tool creation and execution
+ * - Error cases and edge conditions
+ */
+describe('Agent Handoffs Tests', () => {
+    jest.setTimeout(30000);
+    const createTestConfig = (agents, edges) => ({
+        runId: `handoff-test-${Date.now()}-${Math.random()}`,
+        graphConfig: {
+            type: 'multi-agent',
+            agents,
+            edges,
+        },
+        returnContent: true,
+        skipCleanup: true,
+    });
+    const createBasicAgent = (agentId, instructions) => ({
+        agentId,
+        provider: Providers.ANTHROPIC,
+        clientOptions: {
+            modelName: 'claude-haiku-4-5',
+            apiKey: 'test-key',
+        },
+        instructions,
+        maxContextTokens: 28000,
+    });
+    describe('Basic Handoff Tests', () => {
+        it('should create handoff tool for agent with outgoing handoff edge', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            expect(run.Graph).toBeDefined();
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            expect(agentAContext).toBeDefined();
+            expect(agentAContext?.graphTools).toBeDefined();
+            // Check that handoff tool was created
+            const handoffTool = findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffTool).toBeDefined();
+            expect(getToolDescription(handoffTool)).toBe('Transfer to agent B');
+        });
+        it('should successfully handoff from agent A to agent B', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A. Transfer to agent B.'),
+                createBasicAgent('agent_b', 'You are agent B. Respond to the user.'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B when needed',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            // Override models to simulate handoff behavior
+            run.Graph?.overrideTestModel([
+                'Transferring to agent B', // Agent A response
+                'Hello from agent B', // Agent B response
+            ], 10, [
+                {
+                    id: 'tool_call_1',
+                    name: `${Constants.LC_TRANSFER_TO_}agent_b`,
+                    args: {},
+                },
+            ]);
+            const messages = [new HumanMessage('Hello')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-handoff-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            expect(finalMessages).toBeDefined();
+            expect(finalMessages.length).toBeGreaterThan(1);
+            // Check for tool message indicating handoff
+            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
+            const handoffToolMessage = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffToolMessage).toBeDefined();
+            expect(handoffToolMessage?.content).toContain('transferred to agent_b');
+        });
+        it('should not create handoff tool for agent without outgoing edges', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentBContext = run.Graph.agentContexts.get('agent_b');
+            expect(agentBContext).toBeDefined();
+            // Agent B should not have handoff tools (no outgoing edges)
+            const handoffTools = agentBContext?.graphTools?.filter((tool) => {
+                const name = getToolName(tool);
+                return name?.startsWith(Constants.LC_TRANSFER_TO_) ?? false;
+            });
+            expect(handoffTools?.length ?? 0).toBe(0);
+        });
+    });
+    describe('Bidirectional Handoffs', () => {
+        it('should create handoff tools for both agents in bidirectional setup', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                },
+                {
+                    from: 'agent_b',
+                    to: 'agent_a',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent A',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            const agentBContext = run.Graph.agentContexts.get('agent_b');
+            // Agent A should have tool to transfer to B
+            const agentAHandoffTool = findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(agentAHandoffTool).toBeDefined();
+            // Agent B should have tool to transfer to A
+            const agentBHandoffTool = findToolByName(agentBContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_a`);
+            expect(agentBHandoffTool).toBeDefined();
+        });
+        it('should handle handoff from A to B in bidirectional setup', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                },
+                {
+                    from: 'agent_b',
+                    to: 'agent_a',
+                    edgeType: 'handoff',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            // Simulate single handoff from A to B
+            run.Graph?.overrideTestModel(['Transferring to B', 'Response from B'], 10, [
+                {
+                    id: 'tool_call_1',
+                    name: `${Constants.LC_TRANSFER_TO_}agent_b`,
+                    args: {},
+                },
+            ]);
+            const messages = [new HumanMessage('Start conversation')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-bidirectional-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            expect(finalMessages).toBeDefined();
+            // Should have a handoff tool message
+            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
+            const handoffMessage = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffMessage).toBeDefined();
+        });
+    });
+    describe('Sequential Handoffs (Chain)', () => {
+        it('should create handoff tools for chain of agents A -> B -> C', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+                createBasicAgent('agent_c', 'You are agent C'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                },
+                {
+                    from: 'agent_b',
+                    to: 'agent_c',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent C',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            const agentBContext = run.Graph.agentContexts.get('agent_b');
+            const agentCContext = run.Graph.agentContexts.get('agent_c');
+            // Agent A should have tool to transfer to B
+            expect(findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`)).toBeDefined();
+            // Agent B should have tool to transfer to C
+            expect(findToolByName(agentBContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_c`)).toBeDefined();
+            // Agent C should have no handoff tools
+            const agentCHandoffTools = agentCContext?.graphTools?.filter((tool) => {
+                const name = getToolName(tool);
+                return name?.startsWith(Constants.LC_TRANSFER_TO_) ?? false;
+            });
+            expect(agentCHandoffTools?.length ?? 0).toBe(0);
+        });
+    });
+    describe('Multiple Handoff Options', () => {
+        it('should create multiple handoff tools when agent has multiple outgoing edges', async () => {
+            const agents = [
+                createBasicAgent('router', 'You are a router agent'),
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+                createBasicAgent('agent_c', 'You are agent C'),
+            ];
+            const edges = [
+                {
+                    from: 'router',
+                    to: 'agent_a',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent A for task A',
+                },
+                {
+                    from: 'router',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B for task B',
+                },
+                {
+                    from: 'router',
+                    to: 'agent_c',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent C for task C',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const routerContext = run.Graph.agentContexts.get('router');
+            expect(routerContext).toBeDefined();
+            // Router should have 3 handoff tools
+            const handoffTools = routerContext?.graphTools?.filter((tool) => {
+                const name = getToolName(tool);
+                return name?.startsWith(Constants.LC_TRANSFER_TO_) ?? false;
+            });
+            expect(handoffTools?.length).toBe(3);
+            // Verify each tool exists
+            expect(findToolByName(handoffTools, `${Constants.LC_TRANSFER_TO_}agent_a`)).toBeDefined();
+            expect(findToolByName(handoffTools, `${Constants.LC_TRANSFER_TO_}agent_b`)).toBeDefined();
+            expect(findToolByName(handoffTools, `${Constants.LC_TRANSFER_TO_}agent_c`)).toBeDefined();
+        });
+        it('should route to correct agent based on handoff tool used', async () => {
+            const agents = [
+                createBasicAgent('router', 'You are a router'),
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'router',
+                    to: 'agent_a',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent A',
+                },
+                {
+                    from: 'router',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            // Router chooses agent_b
+            run.Graph?.overrideTestModel(['Routing to agent B', 'Hello from agent B'], 10, [
+                {
+                    id: 'tool_call_1',
+                    name: `${Constants.LC_TRANSFER_TO_}agent_b`,
+                    args: {},
+                },
+            ]);
+            const messages = [new HumanMessage('Route this message')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-routing-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
+            // Should have handoff to agent_b, not agent_a
+            const handoffToB = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffToB).toBeDefined();
+            const handoffToA = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}agent_a`);
+            expect(handoffToA).toBeUndefined();
+        });
+    });
+    describe('Handoffs with Prompts', () => {
+        it('should create handoff tool with prompt parameter when prompt is specified', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B with instructions',
+                    prompt: 'Provide specific instructions for agent B',
+                    promptKey: 'instructions',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            const handoffTool = findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffTool).toBeDefined();
+            // Tool should accept parameters (schema should be defined)
+            expect(getToolSchema(handoffTool)).toBeDefined();
+        });
+        it('should use default promptKey when not specified', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    prompt: 'Instructions for handoff',
+                    // promptKey not specified, should default to 'instructions'
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            const handoffTool = findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffTool).toBeDefined();
+            expect(getToolSchema(handoffTool)).toBeDefined();
+        });
+        it('should include prompt content in handoff tool message', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                    prompt: 'Additional context for agent B',
+                    promptKey: 'context',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            run.Graph?.overrideTestModel(['Transferring with context'], 10, [
+                {
+                    id: 'tool_call_1',
+                    name: `${Constants.LC_TRANSFER_TO_}agent_b`,
+                    args: { context: 'User needs help with booking' },
+                },
+            ]);
+            const messages = [new HumanMessage('Help me')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-prompt-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
+            const handoffMessage = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffMessage).toBeDefined();
+            // Tool message should contain the prompt key and value
+            expect(handoffMessage?.content).toContain('Context:');
+        });
+    });
+    describe('Edge Cases and Error Handling', () => {
+        it('should handle self-referential edge gracefully', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_a',
+                    edgeType: 'handoff',
+                    description: 'Self-handoff (should be allowed but unusual)',
+                },
+            ];
+            // Should not throw during creation
+            expect(async () => {
+                await Run.create(createTestConfig(agents, edges));
+            }).not.toThrow();
+        });
+        it('should handle empty edges array', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [];
+            const run = await Run.create(createTestConfig(agents, edges));
+            expect(run.Graph).toBeDefined();
+            // Agents should have no handoff tools
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            const handoffTools = agentAContext?.graphTools?.filter((tool) => {
+                const name = getToolName(tool);
+                return name?.startsWith(Constants.LC_TRANSFER_TO_) ?? false;
+            });
+            expect(handoffTools?.length ?? 0).toBe(0);
+        });
+        it('should start from first agent when no edges are defined', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [];
+            const run = await Run.create(createTestConfig(agents, edges));
+            run.Graph?.overrideTestModel(['Response from first agent'], 10);
+            const messages = [new HumanMessage('Hello')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-no-edges-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            expect(finalMessages).toBeDefined();
+            expect(finalMessages.length).toBeGreaterThan(0);
+        });
+        it('should handle agents with existing tools alongside handoff tools', async () => {
+            const customTool = new DynamicStructuredTool({
+                name: 'custom_tool',
+                description: 'A custom tool',
+                schema: { type: 'object', properties: {}, required: [] },
+                func: async () => 'Tool result',
+            });
+            const agents = [
+                {
+                    ...createBasicAgent('agent_a', 'You are agent A'),
+                    tools: [customTool],
+                },
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to agent B',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentAContext = run.Graph.agentContexts.get('agent_a');
+            // Agent A should have custom tool in tools and handoff tool in graphTools
+            expect(findToolByName(agentAContext?.tools, 'custom_tool')).toBeDefined();
+            expect(findToolByName(agentAContext?.graphTools, `${Constants.LC_TRANSFER_TO_}agent_b`)).toBeDefined();
+        });
+    });
+    describe('Graph Structure Analysis', () => {
+        it('should correctly identify starting nodes with no incoming edges', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'Starting agent'),
+                createBasicAgent('agent_b', 'Middle agent'),
+                createBasicAgent('agent_c', 'End agent'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                },
+                {
+                    from: 'agent_b',
+                    to: 'agent_c',
+                    edgeType: 'handoff',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            // agent_a should be the starting node (no incoming edges)
+            expect(run.Graph).toBeDefined();
+            // This is internal behavior, but we can test via execution
+            run.Graph?.overrideTestModel(['Response from agent A'], 10);
+            const messages = [new HumanMessage('Start')];
+            const config = {
+                configurable: {
+                    thread_id: 'test-starting-node-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            // Should start from agent_a
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            expect(finalMessages).toBeDefined();
+        });
+        it('should handle multiple starting nodes (parallel entry points)', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'Starting agent A'),
+                createBasicAgent('agent_b', 'Starting agent B'),
+                createBasicAgent('agent_c', 'Shared destination'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_c',
+                    edgeType: 'handoff',
+                },
+                {
+                    from: 'agent_b',
+                    to: 'agent_c',
+                    edgeType: 'handoff',
+                },
+            ];
+            // Both agent_a and agent_b have no incoming edges, so both are starting nodes
+            const run = await Run.create(createTestConfig(agents, edges));
+            expect(run.Graph).toBeDefined();
+        });
+    });
+    describe('Tool Call Before Handoff (Issue #54)', () => {
+        it('should complete handoff when router calls a non-handoff tool in the same turn', async () => {
+            /**
+             * Reproduces the bug from issue #54:
+             * When a router calls a regular tool AND a handoff tool in the same turn,
+             * the filtered messages for the receiving agent end with a ToolMessage.
+             * Previously, instructions were appended as a HumanMessage (tool → user),
+             * which many APIs reject. The fix injects instructions into the last
+             * ToolMessage instead.
+             */
+            const customTool = new DynamicStructuredTool({
+                name: 'list_upload_sessions',
+                description: 'List available upload sessions',
+                schema: { type: 'object', properties: {}, required: [] },
+                func: async () => JSON.stringify({ sessions: [{ id: 'sess_1', status: 'ready' }] }),
+            });
+            const agents = [
+                {
+                    ...createBasicAgent('router', 'You are a router'),
+                    tools: [customTool],
+                    toolMap: new Map([['list_upload_sessions', customTool]]),
+                },
+                createBasicAgent('data_analyst', 'You are a data analyst'),
+            ];
+            const edges = [
+                {
+                    from: 'router',
+                    to: 'data_analyst',
+                    edgeType: 'handoff',
+                    description: 'Transfer to data analyst',
+                    prompt: 'Instructions for the analyst about what to analyze',
+                    promptKey: 'instructions',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            /**
+             * Simulate router calling list_upload_sessions AND handoff in the same turn.
+             * The first model response includes both tool calls.
+             * The second model response is the data_analyst's reply.
+             */
+            run.Graph?.overrideTestModel([
+                'Checking available sessions and transferring to analyst',
+                'Here is my analysis of the available sessions',
+            ], 10, [
+                {
+                    id: 'tool_call_1',
+                    name: 'list_upload_sessions',
+                    args: {},
+                },
+                {
+                    id: 'tool_call_2',
+                    name: `${Constants.LC_TRANSFER_TO_}data_analyst`,
+                    args: { instructions: 'Analyze the upload session data' },
+                },
+            ]);
+            const messages = [
+                new HumanMessage('Check my upload sessions and analyze them'),
+            ];
+            const config = {
+                configurable: {
+                    thread_id: 'test-tool-before-handoff-thread',
+                },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            /**
+             * This should complete without error. Before the fix, the receiving
+             * agent would get an invalid tool → user message sequence.
+             */
+            await run.processStream({ messages }, config);
+            const finalMessages = run.getRunMessages();
+            expect(finalMessages).toBeDefined();
+            expect(finalMessages.length).toBeGreaterThan(1);
+            /** Verify that the handoff occurred */
+            const toolMessages = finalMessages.filter((msg) => msg.getType() === 'tool');
+            const handoffMessage = toolMessages.find((msg) => msg.name === `${Constants.LC_TRANSFER_TO_}data_analyst`);
+            expect(handoffMessage).toBeDefined();
+            /** Verify the flow completed (agent B responded) */
+            const aiMessages = finalMessages.filter((msg) => msg.getType() === 'ai');
+            expect(aiMessages.length).toBeGreaterThanOrEqual(1);
+        });
+    });
+    describe('Handoff Tool Naming', () => {
+        it('should use correct naming convention for handoff tools', async () => {
+            const agents = [
+                createBasicAgent('flight_assistant', 'You handle flights'),
+                createBasicAgent('hotel_assistant', 'You handle hotels'),
+            ];
+            const edges = [
+                {
+                    from: 'flight_assistant',
+                    to: 'hotel_assistant',
+                    edgeType: 'handoff',
+                    description: 'Transfer to hotel booking',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const flightContext = run.Graph.agentContexts.get('flight_assistant');
+            const handoffTool = findToolByName(flightContext?.graphTools, `${Constants.LC_TRANSFER_TO_}hotel_assistant`);
+            expect(handoffTool).toBeDefined();
+            expect(getToolName(handoffTool)).toBe(`${Constants.LC_TRANSFER_TO_}hotel_assistant`);
+        });
+        it('should preserve agent ID format in tool names', async () => {
+            const agents = [
+                createBasicAgent('agent_with_underscores', 'Agent with underscores'),
+                createBasicAgent('AgentWithCamelCase', 'Agent with camel case'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_with_underscores',
+                    to: 'AgentWithCamelCase',
+                    edgeType: 'handoff',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const agentContext = run.Graph.agentContexts.get('agent_with_underscores');
+            const handoffTool = findToolByName(agentContext?.graphTools, `${Constants.LC_TRANSFER_TO_}AgentWithCamelCase`);
+            expect(handoffTool).toBeDefined();
+            expect(getToolName(handoffTool)).toBe(`${Constants.LC_TRANSFER_TO_}AgentWithCamelCase`);
+        });
+    });
+    describe('Handoff Tool Description Enrichment', () => {
+        it('should use agent name and description when edge.description is not provided', async () => {
+            const agents = [
+                createBasicAgent('supervisor', 'You are a supervisor'),
+                {
+                    ...createBasicAgent('data_analyst', 'You analyze data'),
+                    name: 'Data Analyst',
+                    description: 'Analyzes datasets, creates charts, and provides statistical insights',
+                },
+            ];
+            const edges = [
+                {
+                    from: 'supervisor',
+                    to: 'data_analyst',
+                    edgeType: 'handoff',
+                    // No description provided - should auto-generate from agent name + description
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const supervisorContext = run.Graph.agentContexts.get('supervisor');
+            const handoffTool = findToolByName(supervisorContext?.tools, `${Constants.LC_TRANSFER_TO_}data_analyst`);
+            expect(handoffTool).toBeDefined();
+            const description = getToolDescription(handoffTool);
+            expect(description).toContain('Data Analyst');
+            expect(description).toContain('Analyzes datasets');
+        });
+        it('should use agent name without description when only name is available', async () => {
+            const agents = [
+                createBasicAgent('supervisor', 'You are a supervisor'),
+                {
+                    ...createBasicAgent('writer', 'You write things'),
+                    name: 'Content Writer',
+                    // No description field
+                },
+            ];
+            const edges = [
+                {
+                    from: 'supervisor',
+                    to: 'writer',
+                    edgeType: 'handoff',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const supervisorContext = run.Graph.agentContexts.get('supervisor');
+            const handoffTool = findToolByName(supervisorContext?.tools, `${Constants.LC_TRANSFER_TO_}writer`);
+            expect(handoffTool).toBeDefined();
+            const description = getToolDescription(handoffTool);
+            expect(description).toContain('Content Writer');
+        });
+        it('should prefer explicit edge.description over auto-generated description', async () => {
+            const agents = [
+                createBasicAgent('supervisor', 'You are a supervisor'),
+                {
+                    ...createBasicAgent('agent_b', 'You do things'),
+                    name: 'Agent B',
+                    description: 'This is agent B description',
+                },
+            ];
+            const edges = [
+                {
+                    from: 'supervisor',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Custom handoff description that takes priority',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const supervisorContext = run.Graph.agentContexts.get('supervisor');
+            const handoffTool = findToolByName(supervisorContext?.tools, `${Constants.LC_TRANSFER_TO_}agent_b`);
+            expect(handoffTool).toBeDefined();
+            const description = getToolDescription(handoffTool);
+            expect(description).toBe('Custom handoff description that takes priority');
+        });
+        it('should generate meaningful descriptions for multiple handoff targets', async () => {
+            const agents = [
+                createBasicAgent('router', 'You route requests'),
+                {
+                    ...createBasicAgent('sales', 'Handle sales'),
+                    name: 'Sales Agent',
+                    description: 'Handles product pricing, quotes, and purchase orders',
+                },
+                {
+                    ...createBasicAgent('support', 'Handle support'),
+                    name: 'Support Agent',
+                    description: 'Troubleshoots technical issues and handles bug reports',
+                },
+                {
+                    ...createBasicAgent('billing', 'Handle billing'),
+                    name: 'Billing Agent',
+                    description: 'Manages invoices, payments, and subscription changes',
+                },
+            ];
+            const edges = [
+                { from: 'router', to: 'sales', edgeType: 'handoff' },
+                { from: 'router', to: 'support', edgeType: 'handoff' },
+                { from: 'router', to: 'billing', edgeType: 'handoff' },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const routerContext = run.Graph.agentContexts.get('router');
+            const salesTool = findToolByName(routerContext?.tools, `${Constants.LC_TRANSFER_TO_}sales`);
+            const supportTool = findToolByName(routerContext?.tools, `${Constants.LC_TRANSFER_TO_}support`);
+            const billingTool = findToolByName(routerContext?.tools, `${Constants.LC_TRANSFER_TO_}billing`);
+            // Each tool should have a meaningful description from the target agent
+            expect(getToolDescription(salesTool)).toContain('pricing');
+            expect(getToolDescription(supportTool)).toContain('Troubleshoots');
+            expect(getToolDescription(billingTool)).toContain('invoices');
+        });
+        it('should store description in AgentContext', async () => {
+            const agents = [
+                {
+                    ...createBasicAgent('agent_a', 'Instructions for A'),
+                    name: 'Agent Alpha',
+                    description: 'Handles alpha tasks',
+                },
+            ];
+            const edges = [];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const context = run.Graph.agentContexts.get('agent_a');
+            expect(context).toBeDefined();
+            expect(context?.name).toBe('Agent Alpha');
+            expect(context?.description).toBe('Handles alpha tasks');
+        });
+    });
+    describe('Last Active Agent Tracking', () => {
+        it('should return undefined for getLastActiveAgentId before any agent runs', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                { from: 'agent_a', to: 'agent_b', edgeType: 'handoff' },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            // Before running, lastActiveAgentId should be undefined
+            expect(run.getLastActiveAgentId()).toBeUndefined();
+        });
+        it('should return undefined for single-agent graph', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+            ];
+            const config = {
+                runId: `single-agent-test-${Date.now()}`,
+                graphConfig: {
+                    type: 'standard',
+                    agents,
+                },
+                returnContent: true,
+            };
+            const run = await Run.create(config);
+            // Single-agent graph does not have getLastActiveAgentId
+            expect(run.getLastActiveAgentId()).toBeUndefined();
+        });
+        it('should track last active agent after handoff execution', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A. Transfer to B.'),
+                createBasicAgent('agent_b', 'You are agent B.'),
+            ];
+            const edges = [
+                {
+                    from: 'agent_a',
+                    to: 'agent_b',
+                    edgeType: 'handoff',
+                    description: 'Transfer to B',
+                },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            run.Graph?.overrideTestModel(['Transferring to B', 'Hello from B'], 10, [
+                {
+                    id: 'tool_call_handoff',
+                    name: `${Constants.LC_TRANSFER_TO_}agent_b`,
+                    args: {},
+                },
+            ]);
+            const messages = [new HumanMessage('Hello')];
+            const config = {
+                configurable: { thread_id: 'last-active-test' },
+                streamMode: 'values',
+                version: 'v2',
+            };
+            await run.processStream({ messages }, config);
+            // After handoff A -> B, last active agent should be B
+            expect(run.getLastActiveAgentId()).toBe('agent_b');
+        });
+    });
+    describe('Content Tool Compaction in Handoff', () => {
+        it('should compact verbose content_tool ToolMessages during handoff', async () => {
+            const agents = [
+                createBasicAgent('agent_a', 'You are agent A'),
+                createBasicAgent('agent_b', 'You are agent B'),
+            ];
+            const edges = [
+                { from: 'agent_a', to: 'agent_b', edgeType: 'handoff' },
+            ];
+            const run = await Run.create(createTestConfig(agents, edges));
+            const { MultiAgentGraph } = await import('@/graphs/MultiAgentGraph');
+            if (run.Graph instanceof MultiAgentGraph) {
+                // Build a mock message chain with a verbose content_tool ToolMessage
+                const _verboseReadOutput = '"Dashboard.tsx" (content_id: abc123)\nShowing lines 1-200 of 200 total.\n---\n' +
+                    Array.from({ length: 200 }, (_, i) => `  ${i + 1} | const x${i} = ${i};`).join('\n') +
+                    '\n---';
+                const _messages = [
+                    new HumanMessage('Read the file'),
+                    // Simulate AI calling content_tool then transfer
+                    // The processHandoffReception is private, so we test indirectly via the graph execution
+                ];
+                // Verify that a ToolMessage with content_tool name and > 500 chars would be compacted
+                const longContent = 'x'.repeat(600);
+                const toolMsg = new ToolMessage({
+                    content: `First line summary\n${longContent}`,
+                    name: 'content_tool',
+                    tool_call_id: 'test-tc-1',
+                    status: 'success',
+                });
+                // The compaction logic truncates to first line + suffix
+                const firstLine = `First line summary\n${longContent}`.split('\n')[0];
+                expect(firstLine).toBe('First line summary');
+                // ToolMessage content is > 500 chars so it should be compacted
+                expect(toolMsg.content.length).toBeGreaterThan(500);
+            }
+        });
+    });
+});
+//# sourceMappingURL=agent-handoffs.test.js.map