@librechat/agents 3.0.64 → 3.0.65

package/src/agents/AgentContext.ts

@@ -27,6 +27,7 @@ export class AgentContext {
   ): AgentContext {
     const {
       agentId,
+      name,
       provider,
       clientOptions,
       tools,
@@ -43,6 +44,7 @@ export class AgentContext {
 
     const agentContext = new AgentContext({
       agentId,
+      name: name ?? agentId,
       provider,
       clientOptions,
       maxContextTokens,
@@ -85,6 +87,8 @@ export class AgentContext {
 
   /** Agent identifier */
   agentId: string;
+  /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
+  name?: string;
   /** Provider for this specific agent */
   provider: Providers;
   /** Client options for this agent */
@@ -145,9 +149,17 @@ export class AgentContext {
   tokenCalculationPromise?: Promise<void>;
   /** Format content blocks as strings (for legacy compatibility) */
   useLegacyContent: boolean = false;
+  /**
+   * Handoff context when this agent receives control via handoff.
+   * Contains source agent name for system message identity context.
+   */
+  handoffContext?: {
+    sourceAgentName: string;
+  };
 
   constructor({
     agentId,
+    name,
     provider,
     clientOptions,
     maxContextTokens,
@@ -164,6 +176,7 @@ export class AgentContext {
     useLegacyContent,
   }: {
     agentId: string;
+    name?: string;
     provider: Providers;
     clientOptions?: t.ClientOptions;
     maxContextTokens?: number;
@@ -180,6 +193,7 @@ export class AgentContext {
     useLegacyContent?: boolean;
   }) {
     this.agentId = agentId;
+    this.name = name;
     this.provider = provider;
     this.clientOptions = clientOptions;
     this.maxContextTokens = maxContextTokens;
@@ -293,27 +307,61 @@ export class AgentContext {
 
   /**
    * Builds the raw instructions string (without creating SystemMessage).
+   * Includes agent identity preamble and handoff context when available.
    */
   private buildInstructionsString(): string {
-    let result = this.instructions ?? '';
+    const parts: string[] = [];
+
+    /** Build agent identity and handoff context preamble */
+    const identityPreamble = this.buildIdentityPreamble();
+    if (identityPreamble) {
+      parts.push(identityPreamble);
+    }
 
+    /** Add main instructions */
+    if (this.instructions != null && this.instructions !== '') {
+      parts.push(this.instructions);
+    }
+
+    /** Add additional instructions */
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
     ) {
-      result = result
-        ? `${result}\n\n${this.additionalInstructions}`
-        : this.additionalInstructions;
+      parts.push(this.additionalInstructions);
     }
 
+    /** Add programmatic tools documentation */
     const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
     if (programmaticToolsDoc) {
-      result = result
-        ? `${result}${programmaticToolsDoc}`
-        : programmaticToolsDoc;
+      parts.push(programmaticToolsDoc);
     }
 
-    return result;
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Builds the agent identity preamble including handoff context if present.
+   * This helps the agent understand its role in the multi-agent workflow.
+   */
+  private buildIdentityPreamble(): string {
+    /** Only include preamble if we have handoff context (indicates multi-agent workflow) */
+    if (!this.handoffContext) return '';
+
+    /** Use name (falls back to agentId if not provided) */
+    const displayName = this.name ?? this.agentId;
+
+    const lines: string[] = [];
+    lines.push('## Agent Context');
+    lines.push(`You are the "${displayName}" agent.`);
+
+    if (this.handoffContext.sourceAgentName) {
+      lines.push(
+        `Control was transferred to you from the "${this.handoffContext.sourceAgentName}" agent.`
+      );
+    }
+
+    return lines.join('\n');
   }
 
   /**
@@ -393,6 +441,7 @@ export class AgentContext {
     this.tokenTypeSwitch = undefined;
     this.currentTokenType = ContentTypes.TEXT;
     this.discoveredToolNames.clear();
+    this.handoffContext = undefined;
   }
 
   /**
@@ -472,6 +521,28 @@ export class AgentContext {
     return registry;
   }
 
+  /**
+   * Sets the handoff context for this agent.
+   * Call this when the agent receives control via handoff from another agent.
+   * Marks system runnable as stale to include handoff context in system message.
+   * @param sourceAgentName - The name of the agent that handed off to this agent
+   */
+  setHandoffContext(sourceAgentName: string): void {
+    this.handoffContext = { sourceAgentName };
+    this.systemRunnableStale = true;
+  }
+
+  /**
+   * Clears any handoff context.
+   * Call this when resetting the agent or when handoff context is no longer relevant.
+   */
+  clearHandoffContext(): void {
+    if (this.handoffContext) {
+      this.handoffContext = undefined;
+      this.systemRunnableStale = true;
+    }
+  }
+
   /**
    * Marks tools as discovered via tool search.
    * Discovered tools will be included in the next model binding.

package/src/graphs/MultiAgentGraph.ts

@@ -249,8 +249,11 @@ export class MultiAgentGraph extends StandardGraph {
 
       // Create handoff tools for this agent's outgoing edges
       const handoffTools: t.GenericTool[] = [];
+      const sourceAgentName = agentContext.name ?? agentId;
       for (const edge of edges) {
-        handoffTools.push(...this.createHandoffToolsForEdge(edge));
+        handoffTools.push(
+          ...this.createHandoffToolsForEdge(edge, agentId, sourceAgentName)
+        );
       }
 
       // Add handoff tools to the agent's existing tools
@@ -263,8 +266,15 @@ export class MultiAgentGraph extends StandardGraph {
 
   /**
    * Create handoff tools for an edge (handles multiple destinations)
+   * @param edge - The graph edge defining the handoff
+   * @param sourceAgentId - The ID of the agent that will perform the handoff
+   * @param sourceAgentName - The human-readable name of the source agent
    */
-  private createHandoffToolsForEdge(edge: t.GraphEdge): t.GenericTool[] {
+  private createHandoffToolsForEdge(
+    edge: t.GraphEdge,
+    sourceAgentId: string,
+    sourceAgentName: string
+  ): t.GenericTool[] {
     const tools: t.GenericTool[] = [];
     const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
 
@@ -319,6 +329,8 @@ export class MultiAgentGraph extends StandardGraph {
               additional_kwargs: {
                 /** Store destination for programmatic access in handoff detection */
                 handoff_destination: destination,
+                /** Store source agent name for receiving agent to know who handed off */
+                handoff_source_name: sourceAgentName,
               },
             });
 
@@ -377,6 +389,10 @@ export class MultiAgentGraph extends StandardGraph {
                 content,
                 name: toolName,
                 tool_call_id: toolCallId,
+                additional_kwargs: {
+                  /** Store source agent name for receiving agent to know who handed off */
+                  handoff_source_name: sourceAgentName,
+                },
               });
 
               const state = getCurrentTaskInput() as t.BaseGraphState;
@@ -482,19 +498,23 @@ export class MultiAgentGraph extends StandardGraph {
   /**
    * Detects if the current agent is receiving a handoff and processes the messages accordingly.
    * Returns filtered messages with the transfer tool call/message removed, plus any instructions
-   * extracted from the transfer to be injected as a HumanMessage preamble.
+   * and source agent information extracted from the transfer.
    *
    * Supports both single handoffs (last message is the transfer) and parallel handoffs
    * (multiple transfer ToolMessages, need to find the one targeting this agent).
    *
    * @param messages - Current state messages
    * @param agentId - The agent ID to check for handoff reception
-   * @returns Object with filtered messages and extracted instructions, or null if not a handoff
+   * @returns Object with filtered messages, extracted instructions, and source agent, or null if not a handoff
    */
   private processHandoffReception(
     messages: BaseMessage[],
     agentId: string
-  ): { filteredMessages: BaseMessage[]; instructions: string | null } | null {
+  ): {
+    filteredMessages: BaseMessage[];
+    instructions: string | null;
+    sourceAgentName: string | null;
+  } | null {
     if (messages.length === 0) return null;
 
     /**
@@ -550,6 +570,11 @@ export class MultiAgentGraph extends StandardGraph {
     const instructionsMatch = contentStr.match(HANDOFF_INSTRUCTIONS_PATTERN);
     const instructions = instructionsMatch?.[1]?.trim() ?? null;
 
+    /** Extract source agent name from additional_kwargs */
+    const handoffSourceName = toolMessage.additional_kwargs.handoff_source_name;
+    const sourceAgentName =
+      typeof handoffSourceName === 'string' ? handoffSourceName : null;
+
     /** Get the tool_call_id to find and filter the AI message's tool call */
     const toolCallId = toolMessage.tool_call_id;
 
@@ -623,7 +648,7 @@ export class MultiAgentGraph extends StandardGraph {
       filteredMessages.push(msg);
     }
 
-    return { filteredMessages, instructions };
+    return { filteredMessages, instructions, sourceAgentName };
   }
 
   /**
@@ -711,7 +736,21 @@ export class MultiAgentGraph extends StandardGraph {
         );
 
         if (handoffContext !== null) {
-          const { filteredMessages, instructions } = handoffContext;
+          const { filteredMessages, instructions, sourceAgentName } =
+            handoffContext;
+
+          /**
+           * Set handoff context on the receiving agent.
+           * This updates the system message to include agent identity info.
+           */
+          const agentContext = this.agentContexts.get(agentId);
+          if (
+            agentContext &&
+            sourceAgentName != null &&
+            sourceAgentName !== ''
+          ) {
+            agentContext.setHandoffContext(sourceAgentName);
+          }
 
           /** Build messages for the receiving agent */
           let messagesForAgent = filteredMessages;
@@ -726,7 +765,6 @@ export class MultiAgentGraph extends StandardGraph {
           }
 
           /** Update token map if we have a token counter */
-          const agentContext = this.agentContexts.get(agentId);
           if (agentContext?.tokenCounter && hasInstructions) {
             const freshTokenMap: Record<string, number> = {};
             for (

package/src/scripts/test-parallel-handoffs.ts

@@ -58,9 +58,8 @@ When delegating, provide clear instructions to each agent about what they should
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a RESEARCHER. When you receive a task:
-1. Acknowledge the handoff
-2. Provide concise research findings (100-150 words)
-3. Start your response with "📚 RESEARCH FINDINGS:"`,
+1. Provide concise research findings (100-150 words)
+2. Start your response with "📚 RESEARCH FINDINGS:"`,
     },
     {
       agentId: 'writer',
@@ -70,9 +69,8 @@ When delegating, provide clear instructions to each agent about what they should
         apiKey: process.env.ANTHROPIC_API_KEY,
       },
       instructions: `You are a WRITER. When you receive a task:
-1. Acknowledge the handoff
-2. Provide creative content (100-150 words)
-3. Start your response with "✍️ WRITTEN CONTENT:"`,
+1. Provide creative content (100-150 words)
+2. Start your response with "✍️ WRITTEN CONTENT:"`,
     },
   ];
 

package/src/types/graph.ts

@@ -357,6 +357,8 @@ export type MultiAgentGraphInput = StandardGraphInput & {
 
 export interface AgentInputs {
   agentId: string;
+  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
+  name?: string;
   toolEnd?: boolean;
   toolMap?: ToolMap;
   tools?: GraphTools;