@librechat/agents 3.9.1 → 3.9.3

package/src/graphs/handoff.ts

@@ -0,0 +1,263 @@
+import { nanoid } from 'nanoid';
+import { Annotation, Command, Send } from '@langchain/langgraph';
+import type { BaseChannel, OverwriteValue } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type {
+  BaseGraphState,
+  HandoffOutcome,
+  HandoffState,
+  HandoffTransition,
+} from '@/types/graph';
+
+function isSupportedVersion(version: number): boolean {
+  return version === 1;
+}
+
+function isSend(value: string | Send): value is Send {
+  return typeof value !== 'string' && value.lg_name === 'Send';
+}
+
+export type HandoffRequest = Pick<
+  HandoffTransition,
+  'sourceAgentId' | 'targetAgentId' | 'toolCallId' | 'scope'
+>;
+
+type HandoffUpdate = Partial<BaseGraphState> & {
+  handoffRequest?: HandoffRequest;
+};
+
+function sameTransition(a: HandoffTransition, b: HandoffTransition): boolean {
+  return (
+    a.id === b.id &&
+    a.sourceAgentId === b.sourceAgentId &&
+    a.targetAgentId === b.targetAgentId &&
+    a.toolCallId === b.toolCallId &&
+    a.scope === b.scope &&
+    a.depth === b.depth
+  );
+}
+
+/** Union by identity makes checkpoint replay idempotent and parallel merges commutative. */
+export function mergeHandoffState(
+  current: HandoffState | undefined,
+  update: HandoffState | undefined
+): HandoffState | undefined {
+  if (update == null) return current;
+  if (current == null) return update;
+  if (current.executionId !== update.executionId) {
+    throw new Error('Cannot merge handoffs from different logical turns');
+  }
+  if (
+    current.entryAgentId !== update.entryAgentId ||
+    current.maxHandoffs !== update.maxHandoffs
+  ) {
+    throw new Error('Conflicting handoff checkpoint configuration');
+  }
+  const transitions = new Map(
+    current.transitions.map((item) => [item.id, item])
+  );
+  for (const transition of update.transitions) {
+    const existing = transitions.get(transition.id);
+    if (existing != null && !sameTransition(existing, transition)) {
+      throw new Error('Conflicting replayed handoff transition');
+    }
+    transitions.set(transition.id, transition);
+  }
+  return {
+    ...current,
+    parallel: current.parallel || update.parallel,
+    historyComplete:
+      current.historyComplete !== false && update.historyComplete !== false,
+    transitions: [...transitions.values()].sort(
+      (a, b) => a.depth - b.depth || a.id.localeCompare(b.id)
+    ),
+  };
+}
+
+export function handoffStateAnnotation(): BaseChannel<
+  HandoffState | undefined,
+  HandoffState | OverwriteValue<HandoffState | undefined> | undefined
+  > {
+  return Annotation<HandoffState | undefined>({
+    reducer: mergeHandoffState,
+    default: () => undefined,
+  });
+}
+
+export class HandoffLimitError extends Error {
+  constructor(readonly limit: number) {
+    super(`Agent handoff limit (${limit}) reached`);
+    this.name = 'HandoffLimitError';
+  }
+}
+
+/** One owner per graph, never shared with isolated child executions. */
+export class HandoffRouting {
+  private state: HandoffState;
+
+  constructor(
+    private readonly entryAgentId: string,
+    private readonly maxHandoffs: number | undefined,
+    private readonly parallel: boolean
+  ) {
+    this.state = this.freshState();
+  }
+
+  private freshState(): HandoffState {
+    return {
+      version: 1,
+      executionId: nanoid(),
+      entryAgentId: this.entryAgentId,
+      ...(this.maxHandoffs == null ? {} : { maxHandoffs: this.maxHandoffs }),
+      transitions: [],
+      parallel: this.parallel,
+    };
+  }
+
+  start(): HandoffState {
+    this.state = this.freshState();
+    return this.snapshot();
+  }
+
+  resume(state: HandoffState | undefined): void {
+    if (state != null) {
+      this.restore(state);
+      return;
+    }
+    if (this.maxHandoffs != null) {
+      throw new Error(
+        'Cannot enforce a handoff budget on a legacy checkpoint without routing state'
+      );
+    }
+    this.state = { ...this.state, historyComplete: false };
+  }
+
+  restore(state: HandoffState | undefined): void {
+    if (state == null) return;
+    if (!isSupportedVersion(state.version))
+      throw new Error('Unsupported handoff checkpoint version');
+    if (
+      state.entryAgentId !== this.entryAgentId ||
+      state.maxHandoffs !== this.maxHandoffs
+    ) {
+      throw new Error('Cannot resume with a different handoff entry or budget');
+    }
+    if (this.state.executionId !== state.executionId) {
+      if (this.state.transitions.length > 0) {
+        throw new Error('Cannot resume a different handoff execution');
+      }
+      this.state = {
+        ...state,
+        transitions: state.transitions.map((item) => ({ ...item })),
+      };
+      return;
+    }
+    this.state = mergeHandoffState(this.state, state)!;
+  }
+
+  snapshot(): HandoffState {
+    return {
+      ...this.state,
+      transitions: this.state.transitions.map((item) => ({ ...item })),
+    };
+  }
+
+  /** Called after tools settle but before Commands can schedule recipients. */
+  finalize(
+    commands: Command[],
+    input: BaseGraphState,
+    config: RunnableConfig
+  ): void {
+    this.restore(input.handoffState);
+    const updates: HandoffUpdate[] = [];
+    let parallel = this.state.parallel;
+    for (const command of commands) {
+      if (command.graph !== Command.PARENT) continue;
+      const sends = Array.isArray(command.goto)
+        ? command.goto.filter(isSend)
+        : [];
+      parallel ||= sends.length > 1;
+      if (sends.length > 0) {
+        for (const send of sends) updates.push(send.args as HandoffUpdate);
+      } else if (command.update != null) {
+        updates.push(command.update as HandoffUpdate);
+      }
+    }
+    const accepted = new Map(
+      this.state.transitions.map((item) => [item.id, item])
+    );
+    const requests = updates.filter((update) => update.handoffRequest != null);
+    if (requests.length === 0) return;
+    const depth =
+      input.handoffState?.transitions.length ?? this.state.transitions.length;
+    const lastMessage = input.messages.at(-1);
+    for (const update of requests) {
+      const request = update.handoffRequest!;
+      const id = JSON.stringify([
+        this.state.executionId,
+        config.configurable?.checkpoint_ns ?? '',
+        request.sourceAgentId,
+        lastMessage?.id ?? input.messages.length,
+        request.toolCallId,
+      ]);
+      const transition = { ...request, id, depth };
+      const existing = accepted.get(id);
+      if (
+        existing != null &&
+        (existing.targetAgentId !== transition.targetAgentId ||
+          existing.scope !== transition.scope)
+      )
+        throw new Error('Handoff replay changed its destination or scope');
+      accepted.set(id, existing ?? transition);
+    }
+    if (this.maxHandoffs != null && accepted.size > this.maxHandoffs) {
+      throw new HandoffLimitError(this.maxHandoffs);
+    }
+    this.state = {
+      ...this.state,
+      transitions: [...accepted.values()],
+      parallel,
+    };
+    for (const update of requests) delete update.handoffRequest;
+    for (const command of commands) {
+      if (command.graph !== Command.PARENT) continue;
+      command.update = {
+        ...(command.update as HandoffUpdate),
+        handoffState: this.snapshot(),
+      };
+      if (!Array.isArray(command.goto)) continue;
+      command.goto = command.goto.map((destination) =>
+        isSend(destination)
+          ? new Send(destination.node, {
+            ...destination.args,
+            handoffState: this.snapshot(),
+          })
+          : destination
+      );
+    }
+  }
+
+  outcome(reason?: string): HandoffOutcome {
+    const state = this.snapshot();
+    const base = {
+      executionId: state.executionId,
+      entryAgentId: state.entryAgentId,
+      transitions: state.transitions,
+    };
+    if (reason != null) return { ...base, status: 'incomplete', reason };
+    if (state.historyComplete === false)
+      return { ...base, status: 'incomplete', reason: 'legacy_checkpoint' };
+    const persistent = state.transitions.filter(
+      (item) => item.scope === 'conversation'
+    );
+    if (persistent.length === 0) return { ...base, status: 'unchanged' };
+    if (state.parallel) return { ...base, status: 'ambiguous' };
+    const last = persistent.reduce((a, b) => (a.depth > b.depth ? a : b));
+    return {
+      ...base,
+      status: 'candidate',
+      agentId: last.targetAgentId,
+      transitionId: last.id,
+    };
+  }
+}

package/src/graphs/index.ts

@@ -2,3 +2,5 @@ export * from './Graph';
 export * from './MultiAgentGraph';
 export * from './createGraph';
 export type * from './graphFactory';
+
+export { HandoffLimitError } from './handoff';

package/src/messages/contextPruning.ts

@@ -26,6 +26,7 @@ import {
   serializeToolContentBounded,
 } from '@/utils/toolContent';
 import { resolveContextPruningSettings } from './contextPruningSettings';
+import { sliceWithoutSplittingSurrogates } from '@/utils/truncation';
 
 /**
  * Applies head+tail soft-trim to tool result content.
@@ -36,7 +37,11 @@ function softTrimContent(
 ): string {
   const { headChars, tailChars } = settings;
   const indicator = `\n\n… [soft-trimmed: ${content.length} chars → ${headChars + tailChars} chars, middle removed] …\n\n`;
-  return content.slice(0, headChars) + indicator + content.slice(-tailChars);
+  return (
+    sliceWithoutSplittingSurrogates(content, 0, headChars) +
+    indicator +
+    sliceWithoutSplittingSurrogates(content, -tailChars)
+  );
 }
 
 export interface ContextPruningResult {
@@ -140,7 +145,8 @@ export function applyContextPruning(params: {
     }
     const content = message.content;
     const contentLength = getToolContentCharLength(content);
-    const eligibilityContent = params.canonicalMessages?.[i]?.content ?? content;
+    const eligibilityContent =
+      params.canonicalMessages?.[i]?.content ?? content;
     if (
       getToolContentCharLength(eligibilityContent) <
       settings.minPrunableToolChars

package/src/messages/prune.ts

@@ -19,6 +19,7 @@ import {
   HARD_MAX_TOOL_CALL_INPUT_CHARS,
   HARD_MAX_TOOL_RESULT_CHARS,
   MIN_JSON_VALUE_CHARS,
+  sliceWithoutSplittingSurrogates,
   calculateMaxToolCallInputChars,
   calculateMaxToolResultChars,
 } from '@/utils/truncation';
@@ -1591,7 +1592,8 @@ function createBoundedTruncationValue(
     const next = Math.ceil((low + high) / 2);
     const candidate = {
       _truncated:
-        TOOL_INPUT_TRUNCATION_MARKER + canonicalPrefix.slice(0, next),
+        TOOL_INPUT_TRUNCATION_MARKER +
+        sliceWithoutSplittingSurrogates(canonicalPrefix, 0, next),
       _originalChars: originalChars,
     };
     if (JSON.stringify(candidate).length <= normalizedMaxChars) {
@@ -1604,7 +1606,8 @@ function createBoundedTruncationValue(
     // Keep the marker separate from a pure canonical prefix so another,
     // slightly smaller cap can be derived without nesting the envelope.
     _truncated:
-      TOOL_INPUT_TRUNCATION_MARKER + canonicalPrefix.slice(0, low),
+      TOOL_INPUT_TRUNCATION_MARKER +
+      sliceWithoutSplittingSurrogates(canonicalPrefix, 0, low),
     _originalChars: originalChars,
   };
 }
@@ -1847,8 +1850,12 @@ function projectStringInputWithinLimit(
   return {
     value:
       marker.length >= normalizedMaxChars
-        ? prefix.slice(0, normalizedMaxChars)
-        : prefix.slice(0, normalizedMaxChars - marker.length) + marker,
+        ? sliceWithoutSplittingSurrogates(prefix, 0, normalizedMaxChars)
+        : sliceWithoutSplittingSurrogates(
+          prefix,
+          0,
+          normalizedMaxChars - marker.length
+        ) + marker,
     changed: true,
   };
 }
@@ -2366,7 +2373,9 @@ function applyToolCallInputCaps(params: {
         additionalKwargsChanges
       );
     }
-    if (capped.response_metadata.output !== canonical.response_metadata.output) {
+    if (
+      capped.response_metadata.output !== canonical.response_metadata.output
+    ) {
       changes.response_metadata = cloneWithProjectedProperties(
         current.response_metadata,
         { output: capped.response_metadata.output }
@@ -2523,11 +2532,7 @@ export function createPruneMessages(factoryParams: PruneMessagesFactoryParams) {
       originalToolContent.clear();
       originalToolContentSize = 0;
     }
-    for (
-      let i = toolExchangeWidthThrough;
-      i < canonicalMessages.length;
-      i++
-    ) {
+    for (let i = toolExchangeWidthThrough; i < canonicalMessages.length; i++) {
       maxToolExchangeWidth = Math.max(
         maxToolExchangeWidth,
         getToolCallIds(canonicalMessages[i]).size

package/src/run.ts

@@ -111,6 +111,7 @@ import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
 import { resolveClientOptionsModel } from '@/llm/request';
+import { HandoffLimitError } from '@/graphs/handoff';
 import { createGraph } from '@/graphs/createGraph';
 import { isFadingTier } from '@/messages/fading';
 import { resolveMaxSeals } from '@/llm/preempt';
@@ -291,6 +292,7 @@ function getInterruptHookSessionId(payload: unknown): string | undefined {
 type InterruptStateSnapshot = {
   config?: RunnableConfig;
   values?: {
+    handoffState?: t.HandoffState;
     messages?: BaseMessage[];
     runStepState?: t.RunStepResumeState;
   };
@@ -512,6 +514,7 @@ export class Run<_T extends t.BaseGraphState> {
   /** Distinguishes sibling forks started from the same explicit checkpoint. */
   private checkpointForkSeq = 0;
   private _haltedReason: string | undefined;
+  private _handoffOutcome?: t.HandoffOutcome;
 
   private constructor(config: Partial<t.RunConfig>) {
     const runId = config.runId ?? '';
@@ -683,7 +686,7 @@ export class Run<_T extends t.BaseGraphState> {
   private createMultiAgentGraph(
     config: t.MultiAgentGraphConfig
   ): t.CompiledStateWorkflow {
-    const { agents, edges, compileOptions } = config;
+    const { agents, edges, compileOptions, entryAgentId, maxHandoffs } = config;
 
     const multiAgentGraph = createGraph({
       kind: 'multi-agent',
@@ -691,6 +694,8 @@ export class Run<_T extends t.BaseGraphState> {
         runId: this.id,
         agents,
         edges,
+        entryAgentId,
+        maxHandoffs,
         langfuse: this.langfuse,
         tokenCounter: this.tokenCounter,
         indexTokenCountMap: this.indexTokenCountMap,
@@ -1237,6 +1242,7 @@ export class Run<_T extends t.BaseGraphState> {
     }
     const graphRunnable = this.graphRunnable;
     const graph = this.Graph;
+    this._handoffOutcome = undefined;
 
     /**
      * `Command` inputs (`Command({ resume, update?, goto? })`) are
@@ -1347,6 +1353,7 @@ export class Run<_T extends t.BaseGraphState> {
             checkpointId === '' ? 0 : ++this.checkpointForkSeq,
           ]);
       graph.resetValues(streamOptions?.keepContent, checkpointScope);
+      graph.handoffRouting?.start();
       graph.startStopContinuationExecution(nanoid());
     }
     this._interrupt = undefined;
@@ -1482,9 +1489,18 @@ export class Run<_T extends t.BaseGraphState> {
 
     const consumeStream = async (): Promise<void> => {
       let streamInputs: t.IState | Command = inputs;
-      if (!isResume && this.hasCheckpointer) {
+      if (!isResume && graph.handoffRouting != null) {
         streamInputs = {
           ...(inputs as t.IState),
+          handoffState: graph.handoffRouting.snapshot(),
+        };
+      }
+      if (!isResume && this.hasCheckpointer) {
+        streamInputs = {
+          ...(streamInputs as t.IState),
+          ...(graph.handoffRouting == null
+            ? {}
+            : { handoffState: new Overwrite(graph.handoffRouting.snapshot()) }),
           runStepState: new Overwrite(graph.createRunStepResumeState()),
         } as unknown as t.IState;
       } else if (overwriteLegacyResumeState) {
@@ -1679,6 +1695,7 @@ export class Run<_T extends t.BaseGraphState> {
                 ? injected
                 : [...graph.messages, ...injected],
               runStepState: graph.createRunStepResumeState(),
+              handoffState: graph.handoffRouting?.snapshot(),
             };
             streamConfig = completedSegmentConfig;
             continue;
@@ -1716,6 +1733,8 @@ export class Run<_T extends t.BaseGraphState> {
     } catch (err) {
       terminalAt = Date.now();
       streamThrew = true;
+      if (err instanceof HandoffLimitError)
+        this._haltedReason = 'handoff_limit';
       await langfuseHandler?.handleChainError(
         err instanceof Error ? err : new Error(String(err)),
         this.id
@@ -1860,6 +1879,13 @@ export class Run<_T extends t.BaseGraphState> {
        * `HumanInTheLoopConfig` JSDoc.
        */
       const awaitingResume = this.isAwaitingResume(streamThrew);
+      this._handoffOutcome = graph.handoffRouting?.outcome(
+        this.getHandoffIncompleteReason(
+          streamThrew,
+          awaitingResume,
+          config.signal
+        )
+      );
       if (!this.skipCleanup && !awaitingResume) {
         this.Graph.clearHeavyState();
       }
@@ -1921,6 +1947,31 @@ export class Run<_T extends t.BaseGraphState> {
     return this._haltedReason;
   }
 
+  private getHandoffIncompleteReason(
+    streamThrew: boolean,
+    awaitingResume: boolean,
+    signal?: AbortSignal
+  ): string | undefined {
+    if (this._haltedReason != null) return this._haltedReason;
+    if (signal?.aborted === true || this.Graph?.signal?.aborted === true) {
+      return 'aborted';
+    }
+    if (streamThrew) return 'error';
+    if (awaitingResume) return 'interrupted';
+    if (this.Graph?.subagentScope === true) return 'subagent';
+    return undefined;
+  }
+
+  /** Execution evidence only. The host must authorize and durably commit a candidate. */
+  getHandoffOutcome(): t.HandoffOutcome | undefined {
+    const outcome = this._handoffOutcome;
+    if (outcome == null) return undefined;
+    return {
+      ...outcome,
+      transitions: outcome.transitions.map((item) => ({ ...item })),
+    };
+  }
+
   /**
    * Resume a paused HITL run with the value the user (or whatever
    * decided the interrupt) supplied. The default `TResume` covers the
@@ -2134,6 +2185,7 @@ export class Run<_T extends t.BaseGraphState> {
     const snapshot = await workflow.getState(callerConfig as RunnableConfig, {
       subgraphs: true,
     });
+    this.Graph?.handoffRouting?.resume(snapshot.values?.handoffState);
     const persistedInterrupt = getFirstPersistedInterrupt(snapshot);
     if (persistedInterrupt == null) {
       return;

package/src/tools/ToolNode.ts

@@ -974,8 +974,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * other's in-flight state.
    */
   private anonBatchCounter: number = 0;
+  private handoffRouting?: t.ToolNodeOptions['handoffRouting'];
 
   constructor({
+    handoffRouting,
     tools,
     toolMap,
     name,
@@ -1219,6 +1221,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.runLangfuse = runLangfuse;
     this.agentLangfuse = agentLangfuse;
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+    this.handoffRouting = handoffRouting;
     this.toolCallStepIds = toolCallStepIds;
     this.handleToolErrors = handleToolErrors ?? this.handleToolErrors;
     this.loadRuntimeTools = loadRuntimeTools;
@@ -3221,10 +3224,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
   private retainCodeSessionInputsFromRequests(
     requests: Iterable<t.ToolCallRequest>,
-    baselineByRequestId: ReadonlyMap<
-      string,
-      ReadonlyMap<string, string>
-    >
+    baselineByRequestId: ReadonlyMap<string, ReadonlyMap<string, string>>
   ): void {
     if (!this.sessions) {
       return;
@@ -5140,8 +5140,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         call.id == null
           ? undefined
           : baseContext.resolvedArgsByCallId?.get(call.id);
-      const codeSessionBaseline =
-        baseContext.codeSessionBaselineByCallId?.get(call.id ?? '');
+      const codeSessionBaseline = baseContext.codeSessionBaselineByCallId?.get(
+        call.id ?? ''
+      );
       const result: SettledDirectToolResult = {
         proposal: structuredClone({
           name: call.name,
@@ -6073,6 +6074,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (replayBatchKey != null) {
       this.settledDirectResultsByBatch.delete(replayBatchKey);
     }
+    if (!Array.isArray(input) && !this.isSendInput(input)) {
+      this.handoffRouting?.finalize(
+        combinedOutputs.filter(isCommand),
+        input as t.BaseGraphState,
+        config
+      );
+    }
     return combinedOutputs as T;
   }
 

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. */