@illuma-ai/agents 1.1.15 → 1.1.17

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

@@ -94,7 +94,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -128,7 +128,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B when needed',
         },
       ];
@@ -192,7 +192,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -223,13 +223,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A',
         },
       ];
@@ -268,12 +268,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -334,13 +334,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent C',
         },
       ];
@@ -395,19 +395,19 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A for task A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B for task B',
         },
         {
           from: 'router',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent C for task C',
         },
       ];
@@ -449,13 +449,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -519,7 +519,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B with instructions',
           prompt: 'Provide specific instructions for agent B',
           promptKey: 'instructions',
@@ -551,7 +551,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           prompt: 'Instructions for handoff',
           // promptKey not specified, should default to 'instructions'
         },
@@ -581,7 +581,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
           prompt: 'Additional context for agent B',
           promptKey: 'context',
@@ -638,7 +638,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Self-handoff (should be allowed but unusual)',
         },
       ];
@@ -724,7 +724,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -759,12 +759,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -806,12 +806,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -853,7 +853,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'data_analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to data analyst',
           prompt: 'Instructions for the analyst about what to analyze',
           promptKey: 'instructions',
@@ -939,7 +939,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'flight_assistant',
           to: 'hotel_assistant',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to hotel booking',
         },
       ];
@@ -970,7 +970,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_with_underscores',
           to: 'AgentWithCamelCase',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -1007,7 +1007,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'data_analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           // No description provided - should auto-generate from agent name + description
         },
       ];
@@ -1042,7 +1042,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'writer',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -1075,7 +1075,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Custom handoff description that takes priority',
         },
       ];
@@ -1118,9 +1118,9 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'sales', edgeType: EdgeType.HANDOFF },
-        { from: 'router', to: 'support', edgeType: EdgeType.HANDOFF },
-        { from: 'router', to: 'billing', edgeType: EdgeType.HANDOFF },
+        { from: 'router', to: 'sales', edgeType: EdgeType.TRANSFER },
+        { from: 'router', to: 'support', edgeType: EdgeType.TRANSFER },
+        { from: 'router', to: 'billing', edgeType: EdgeType.TRANSFER },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));
@@ -1176,7 +1176,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));
@@ -1215,7 +1215,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to B',
         },
       ];
@@ -1255,7 +1255,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));

package/src/specs/thinking-handoff.test.ts

@@ -77,7 +77,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'specialist',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to specialist for detailed analysis',
         },
       ];
@@ -166,7 +166,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -223,7 +223,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'coordinator',
           to: 'analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to analyst for deep analysis',
         },
       ];
@@ -297,7 +297,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -360,7 +360,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'bedrock_specialist',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to Bedrock specialist',
         },
       ];
@@ -450,12 +450,12 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'router',
           to: 'processor',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'processor',
           to: 'reviewer',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -538,7 +538,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -603,7 +603,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 

package/src/types/graph.ts

@@ -48,6 +48,16 @@ export interface ChatModel {
   ) => Promise<AIMessageChunk>;
 }
 
+/** Payload for ON_AGENT_TRANSITION events */
+export type AgentTransitionEvent = {
+  sourceAgentId?: string;
+  sourceAgentName?: string;
+  destinationAgentId: string;
+  destinationAgentName: string;
+  edgeType: string; // 'handoff' | 'transfer' | 'sequence'
+  timestamp: number;
+};
+
 export type GraphNode = GraphNodeKeys | typeof START;
 export type ClientCallback<T extends unknown[]> = (
   graph: StandardGraph,
@@ -340,14 +350,18 @@ export type GraphEdge = {
   description?: string;
   /** Can return boolean or specific destination(s) */
   condition?: (state: BaseGraphState) => boolean | string | string[];
-  /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */
+  /**
+   * EdgeType.HANDOFF — true agent handoff, parent calls child inline and gets result back.
+   * EdgeType.TRANSFER — one-way transfer, parent exits and child takes over.
+   * EdgeType.SEQUENCE — fixed graph edges for sequential/parallel transitions.
+   */
   edgeType?: import('@/common').EdgeType;
   /**
-   * For direct edges: Optional prompt to add when transitioning through this edge.
+   * For sequence edges: Optional prompt to add when transitioning through this edge.
    * String prompts can include variables like {results} which will be replaced with
    * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.
    *
-   * For handoff edges: Description for the input parameter that the handoff tool accepts,
+   * For transfer edges: Description for the input parameter that the transfer tool accepts,
    * allowing the supervisor to pass specific instructions/context to the transferred agent.
    */
   prompt?:
@@ -362,15 +376,17 @@ export type GraphEdge = {
    */
   excludeResults?: boolean;
   /**
-   * For handoff edges: Customizes the parameter name for the handoff input.
+   * For transfer edges: Customizes the parameter name for the transfer input.
    * Defaults to "instructions" if not specified.
-   * Only applies when prompt is provided for handoff edges.
+   * Only applies when prompt is provided for transfer edges.
+   *
+   * For handoff edges: Customizes the parameter name for the handoff instruction input.
    */
   promptKey?: string;
   /**
-   * For delegate edges: Maximum characters for the result returned to the parent.
+   * For handoff edges: Maximum characters for the result returned to the parent.
    * Uses head/tail truncation (60/40 split) to preserve key findings and conclusions.
-   * Defaults to Constants.DEFAULT_DELEGATE_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
+   * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
    */
   maxResultChars?: number;
 };