@librechat/agents 3.9.2 → 3.9.3

package/src/types/graph.ts

@@ -78,9 +78,45 @@ export type SystemCallbacks = {
     : never;
 };
 
+/** An executed, SDK-generated handoff, identified independently of stream events. */
+export interface HandoffTransition {
+  id: string;
+  sourceAgentId: string;
+  targetAgentId: string;
+  toolCallId: string;
+  scope: 'turn' | 'conversation';
+  /** Causal order: number of handoffs visible at this batch's input. */
+  depth: number;
+}
+
+/** Versioned graph checkpoint payload, scoped to one logical user turn. */
+export interface HandoffState {
+  version: 1;
+  executionId: string;
+  entryAgentId: string;
+  maxHandoffs?: number;
+  transitions: HandoffTransition[];
+  parallel: boolean;
+  /** False when resuming an older checkpoint without complete routing provenance. */
+  historyComplete?: boolean;
+}
+
+/** Only a candidate from a completed top-level run may be promoted by a host. */
+export type HandoffOutcome = {
+  executionId: string;
+  entryAgentId: string;
+  transitions: readonly HandoffTransition[];
+} & (
+  | { status: 'candidate'; agentId: string; transitionId: string }
+  | { status: 'unchanged' | 'ambiguous' }
+  | { status: 'incomplete'; reason: string }
+);
+
 export type BaseGraphState = {
   messages: BaseMessage[];
   runStepState?: RunStepResumeState;
+  /** SDK-owned routing state; hosts must not synthesize it from messages. */
+  handoffState?: HandoffState;
   /**
    * The summary a summarize-only run produced. Kept in state because such a
    * run has no assistant reply: trace roots report it as the run's output
@@ -434,6 +470,8 @@ export type GraphEdge = {
   condition?: (state: BaseGraphState) => boolean | string | string[];
   /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
   edgeType?: 'handoff' | 'direct';
+  /** Host may promote the destination after successful top-level completion. */
+  handoffScope?: 'turn' | 'conversation';
   /**
    * For direct edges: Optional prompt to add when transitioning through this edge.
    * String prompts can include variables like {results} which will be replaced with
@@ -463,15 +501,20 @@ export type GraphEdge = {
 
 export type GraphSubagentEdge = Omit<
   GraphEdge,
-  'edgeType' | 'condition' | 'promptKey'
+  'edgeType' | 'condition' | 'promptKey' | 'handoffScope'
 > & {
   edgeType: 'direct';
   condition?: never;
   promptKey?: never;
+  handoffScope?: never;
 };
 
 export type MultiAgentGraphInput = StandardGraphInput & {
   edges: GraphEdge[];
+  /** Explicit fresh-turn entry; absent preserves topology-inferred entry points. */
+  entryAgentId?: string;
+  /** Shared logical-turn handoff cap. Zero forbids handoffs; absent uses only recursion limits. */
+  maxHandoffs?: number;
   /** Captures the designated member's final AI turn in graph state. */
   resultAgentId?: string;
   /** Optional per-member Pregel budget when the outer graph has its own topology budget. */

package/src/types/run.ts

@@ -115,11 +115,13 @@ export type MultiAgentGraphConfig = {
   compileOptions?: g.CompileOptions;
   agents: g.AgentInputs[];
   edges: g.GraphEdge[];
+  entryAgentId?: string;
+  maxHandoffs?: number;
 };
 
 export type StandardGraphConfig = Omit<
   MultiAgentGraphConfig,
-  'edges' | 'type'
+  'edges' | 'type' | 'entryAgentId' | 'maxHandoffs'
 > & { type?: 'standard'; signal?: AbortSignal };
 
 /**

package/src/types/tools.ts

@@ -14,6 +14,7 @@ import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { LangfuseConfig, SubagentExecutionContext } from './graph';
 import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
+import type { HandoffRouting } from '@/graphs/handoff';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { HookRegistry } from '@/hooks';
 
@@ -117,6 +118,8 @@ export type EagerEventToolCallChunkState = {
 };
 
 export type ToolNodeOptions = {
+  /** @internal Admission shared by tool nodes belonging to one multi-agent graph. */
+  handoffRouting?: Pick<HandoffRouting, 'finalize'>;
   name?: string;
   tags?: string[];
   /** Enables LangChain/LangGraph tracing for this ToolNode. Defaults to false. */