feat: Add support for agent handoffs with edges in agent forms and schemas

client/src/common/agents-types.ts

@@ -1,9 +1,10 @@
 import { AgentCapabilities, ArtifactModes } from 'librechat-data-provider';
 import type {
-  Agent,
-  AgentProvider,
   AgentModelParameters,
   SupportContact,
+  AgentProvider,
+  GraphEdge,
+  Agent,
 } from 'librechat-data-provider';
 import type { OptionWithIcon, ExtendedFile } from './types';
 
@@ -34,6 +35,7 @@ export type AgentForm = {
   tools?: string[];
   provider?: AgentProvider | OptionWithIcon;
   agent_ids?: string[];
+  edges?: GraphEdge[];
   [AgentCapabilities.artifacts]?: ArtifactModes | string;
   recursion_limit?: number;
   support_contact?: SupportContact;

client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx

@@ -5,6 +5,7 @@ import { useFormContext, Controller } from 'react-hook-form';
 import type { AgentForm } from '~/common';
 import { useAgentPanelContext } from '~/Providers';
 import MaxAgentSteps from './MaxAgentSteps';
+import AgentHandoffs from './AgentHandoffs';
 import { useLocalize } from '~/hooks';
 import AgentChain from './AgentChain';
 import { Panel } from '~/common';
@@ -41,6 +42,12 @@ export default function AdvancedPanel() {
       </div>
       <div className="flex flex-col gap-4 px-2">
         <MaxAgentSteps />
+        <Controller
+          name="edges"
+          control={control}
+          defaultValue={[]}
+          render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}
+        />
         {chainEnabled && (
           <Controller
             name="agent_ids"

client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsx

@@ -0,0 +1,311 @@
+import React, { useState, useMemo, useCallback, useEffect } from 'react';
+import { EModelEndpoint } from 'librechat-data-provider';
+import { X, Waypoints, PlusCircle, ChevronDown } from 'lucide-react';
+import {
+  Label,
+  Input,
+  Textarea,
+  HoverCard,
+  CircleHelpIcon,
+  HoverCardPortal,
+  ControlCombobox,
+  HoverCardContent,
+  HoverCardTrigger,
+} from '@librechat/client';
+import type { TMessage, GraphEdge } from 'librechat-data-provider';
+import type { ControllerRenderProps } from 'react-hook-form';
+import type { AgentForm, OptionWithIcon } from '~/common';
+import MessageIcon from '~/components/Share/MessageIcon';
+import { useAgentsMapContext } from '~/Providers';
+import { useLocalize } from '~/hooks';
+import { ESide } from '~/common';
+
+interface AgentHandoffsProps {
+  field: ControllerRenderProps<AgentForm, 'edges'>;
+  currentAgentId: string;
+}
+
+/** TODO: make configurable */
+const MAX_HANDOFFS = 10;
+
+const AgentHandoffs: React.FC<AgentHandoffsProps> = ({ field, currentAgentId }) => {
+  const localize = useLocalize();
+  const [newAgentId, setNewAgentId] = useState('');
+  const [expandedIndices, setExpandedIndices] = useState<Set<number>>(new Set());
+  const agentsMap = useAgentsMapContext();
+  const edgesValue = field.value;
+  const edges = useMemo(() => edgesValue || [], [edgesValue]);
+
+  const agents = useMemo(() => (agentsMap ? Object.values(agentsMap) : []), [agentsMap]);
+
+  const selectableAgents = useMemo(
+    () =>
+      agents
+        .filter((agent) => agent?.id !== currentAgentId)
+        .map(
+          (agent) =>
+            ({
+              label: agent?.name || '',
+              value: agent?.id || '',
+              icon: (
+                <MessageIcon
+                  message={
+                    {
+                      endpoint: EModelEndpoint.agents,
+                      isCreatedByUser: false,
+                    } as TMessage
+                  }
+                  agent={agent}
+                />
+              ),
+            }) as OptionWithIcon,
+        ),
+    [agents, currentAgentId],
+  );
+
+  const getAgentDetails = useCallback((id: string) => agentsMap?.[id], [agentsMap]);
+
+  useEffect(() => {
+    if (newAgentId && edges.length < MAX_HANDOFFS) {
+      const newEdge: GraphEdge = {
+        from: currentAgentId,
+        to: newAgentId,
+        edgeType: 'handoff',
+      };
+      field.onChange([...edges, newEdge]);
+      setNewAgentId('');
+    }
+  }, [newAgentId, edges, field, currentAgentId]);
+
+  const removeHandoffAt = (index: number) => {
+    field.onChange(edges.filter((_, i) => i !== index));
+    // Also remove from expanded set
+    setExpandedIndices((prev) => {
+      const newSet = new Set(prev);
+      newSet.delete(index);
+      return newSet;
+    });
+  };
+
+  const updateHandoffAt = (index: number, agentId: string) => {
+    const updated = [...edges];
+    updated[index] = { ...updated[index], to: agentId };
+    field.onChange(updated);
+  };
+
+  const updateHandoffDetailsAt = (index: number, updates: Partial<GraphEdge>) => {
+    const updated = [...edges];
+    updated[index] = { ...updated[index], ...updates };
+    field.onChange(updated);
+  };
+
+  const toggleExpanded = (index: number) => {
+    setExpandedIndices((prev) => {
+      const newSet = new Set(prev);
+      if (newSet.has(index)) {
+        newSet.delete(index);
+      } else {
+        newSet.add(index);
+      }
+      return newSet;
+    });
+  };
+
+  const getTargetAgentId = (to: string | string[]): string => {
+    return Array.isArray(to) ? to[0] : to;
+  };
+
+  return (
+    <HoverCard openDelay={50}>
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2">
+          <label className="font-semibold text-text-primary">
+            {localize('com_ui_agent_handoffs')}
+          </label>
+          <HoverCardTrigger>
+            <CircleHelpIcon className="h-4 w-4 text-text-tertiary" />
+          </HoverCardTrigger>
+        </div>
+        <div className="text-xs text-text-secondary">
+          {edges.length} / {MAX_HANDOFFS}
+        </div>
+      </div>
+      <div className="space-y-1">
+        {/* Current fixed agent */}
+        <div className="flex h-10 items-center justify-between rounded-md border border-border-medium bg-surface-primary-contrast px-3 py-2">
+          <div className="flex items-center gap-2">
+            <div className="flex h-6 w-6 items-center justify-center overflow-hidden rounded-full">
+              <MessageIcon
+                message={
+                  {
+                    endpoint: EModelEndpoint.agents,
+                    isCreatedByUser: false,
+                  } as TMessage
+                }
+                agent={currentAgentId && agentsMap ? agentsMap[currentAgentId] : undefined}
+              />
+            </div>
+            <div className="font-medium text-text-primary">
+              {getAgentDetails(currentAgentId)?.name}
+            </div>
+          </div>
+        </div>
+        {edges.length > 0 && <Waypoints className="mx-auto text-text-secondary" size={14} />}
+        {edges.map((edge, idx) => {
+          const targetAgentId = getTargetAgentId(edge.to);
+          const isExpanded = expandedIndices.has(idx);
+
+          return (
+            <React.Fragment key={idx}>
+              <div className="space-y-1">
+                <div className="flex h-10 items-center gap-2 rounded-md border border-border-medium bg-surface-tertiary pr-2">
+                  <ControlCombobox
+                    isCollapsed={false}
+                    ariaLabel={localize('com_ui_agent_var', { 0: localize('com_ui_select') })}
+                    selectedValue={targetAgentId}
+                    setValue={(id) => updateHandoffAt(idx, id)}
+                    selectPlaceholder={localize('com_ui_agent_var', {
+                      0: localize('com_ui_select'),
+                    })}
+                    searchPlaceholder={localize('com_ui_agent_var', {
+                      0: localize('com_ui_search'),
+                    })}
+                    items={selectableAgents}
+                    displayValue={getAgentDetails(targetAgentId)?.name ?? ''}
+                    SelectIcon={
+                      <MessageIcon
+                        message={
+                          {
+                            endpoint: EModelEndpoint.agents,
+                            isCreatedByUser: false,
+                          } as TMessage
+                        }
+                        agent={targetAgentId && agentsMap ? agentsMap[targetAgentId] : undefined}
+                      />
+                    }
+                    className="flex-1 border-border-heavy"
+                    containerClassName="px-0"
+                  />
+                  <button
+                    type="button"
+                    className="rounded p-1 transition hover:bg-surface-hover"
+                    onClick={() => toggleExpanded(idx)}
+                  >
+                    <ChevronDown
+                      size={16}
+                      className={`text-text-secondary transition-transform ${
+                        isExpanded ? 'rotate-180' : ''
+                      }`}
+                    />
+                  </button>
+                  <button
+                    type="button"
+                    className="rounded-xl p-1 transition hover:bg-surface-hover"
+                    onClick={() => removeHandoffAt(idx)}
+                  >
+                    <X size={18} className="text-text-secondary" />
+                  </button>
+                </div>
+
+                {isExpanded && (
+                  <div className="space-y-3 rounded-md border border-border-light bg-surface-primary p-3">
+                    <div>
+                      <Label
+                        htmlFor={`handoff-desc-${idx}`}
+                        className="text-xs text-text-secondary"
+                      >
+                        {localize('com_ui_agent_handoff_description')}
+                      </Label>
+                      <Input
+                        id={`handoff-desc-${idx}`}
+                        placeholder={localize('com_ui_agent_handoff_description_placeholder')}
+                        value={edge.description || ''}
+                        onChange={(e) =>
+                          updateHandoffDetailsAt(idx, { description: e.target.value })
+                        }
+                        className="mt-1 h-8 text-sm"
+                      />
+                    </div>
+
+                    <div>
+                      <Label
+                        htmlFor={`handoff-prompt-${idx}`}
+                        className="text-xs text-text-secondary"
+                      >
+                        {localize('com_ui_agent_handoff_prompt')}
+                      </Label>
+                      <Textarea
+                        id={`handoff-prompt-${idx}`}
+                        placeholder={localize('com_ui_agent_handoff_prompt_placeholder')}
+                        value={typeof edge.prompt === 'string' ? edge.prompt : ''}
+                        onChange={(e) => updateHandoffDetailsAt(idx, { prompt: e.target.value })}
+                        className="mt-1 h-20 resize-none text-sm"
+                      />
+                    </div>
+
+                    {edge.prompt && (
+                      <div>
+                        <Label
+                          htmlFor={`handoff-promptkey-${idx}`}
+                          className="text-xs text-text-secondary"
+                        >
+                          {localize('com_ui_agent_handoff_prompt_key')}
+                        </Label>
+                        <Input
+                          id={`handoff-promptkey-${idx}`}
+                          placeholder={localize('com_ui_agent_handoff_prompt_key_placeholder')}
+                          value={edge.promptKey || ''}
+                          onChange={(e) =>
+                            updateHandoffDetailsAt(idx, { promptKey: e.target.value })
+                          }
+                          className="mt-1 h-8 text-sm"
+                        />
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+              {idx < edges.length - 1 && (
+                <Waypoints className="mx-auto text-text-secondary" size={14} />
+              )}
+            </React.Fragment>
+          );
+        })}
+
+        {edges.length < MAX_HANDOFFS && (
+          <>
+            {edges.length > 0 && <Waypoints className="mx-auto text-text-secondary" size={14} />}
+            <ControlCombobox
+              isCollapsed={false}
+              ariaLabel={localize('com_ui_agent_var', { 0: localize('com_ui_add') })}
+              selectedValue=""
+              setValue={setNewAgentId}
+              selectPlaceholder={localize('com_ui_agent_handoff_add')}
+              searchPlaceholder={localize('com_ui_agent_var', { 0: localize('com_ui_search') })}
+              items={selectableAgents}
+              className="h-10 w-full border-dashed border-border-heavy text-center text-text-secondary hover:text-text-primary"
+              containerClassName="px-0"
+              SelectIcon={<PlusCircle size={16} className="text-text-secondary" />}
+            />
+          </>
+        )}
+
+        {edges.length >= MAX_HANDOFFS && (
+          <p className="pt-1 text-center text-xs italic text-text-tertiary">
+            {localize('com_ui_agent_handoff_max', { 0: MAX_HANDOFFS })}
+          </p>
+        )}
+      </div>
+      <HoverCardPortal>
+        <HoverCardContent side={ESide.Top} className="w-80">
+          <div className="space-y-2">
+            <p className="text-sm text-text-secondary">{localize('com_ui_agent_handoff_info')}</p>
+            <p className="text-sm text-text-secondary">{localize('com_ui_agent_handoff_info_2')}</p>
+          </div>
+        </HoverCardContent>
+      </HoverCardPortal>
+    </HoverCard>
+  );
+};
+
+export default AgentHandoffs;

client/src/components/SidePanel/Agents/AgentPanel.tsx

@@ -177,6 +177,7 @@ export default function AgentPanel() {
         model_parameters,
         provider: _provider,
         agent_ids,
+        edges,
         end_after_tools,
         hide_sequential_outputs,
         recursion_limit,
@@ -201,6 +202,7 @@ export default function AgentPanel() {
             provider,
             model_parameters,
             agent_ids,
+            edges,
             end_after_tools,
             hide_sequential_outputs,
             recursion_limit,
@@ -234,6 +236,7 @@ export default function AgentPanel() {
         provider,
         model_parameters,
         agent_ids,
+        edges,
         end_after_tools,
         hide_sequential_outputs,
         recursion_limit,

client/src/components/SidePanel/Agents/AgentSelect.tsx

@@ -103,6 +103,11 @@ export default function AgentSelect({
           return;
         }
 
+        if (name === 'edges' && Array.isArray(value)) {
+          formValues[name] = value;
+          return;
+        }
+
         if (!keys.has(name)) {
           return;
         }

client/src/locales/en/translation.json

@@ -653,6 +653,17 @@
   "com_ui_agent_chain": "Agent Chain (Mixture-of-Agents)",
   "com_ui_agent_chain_info": "Enables creating sequences of agents. Each agent can access outputs from previous agents in the chain. Based on the \"Mixture-of-Agents\" architecture where agents use previous outputs as auxiliary information.",
   "com_ui_agent_chain_max": "You have reached the maximum of {{0}} agents.",
+  "com_ui_agent_handoffs": "Agent Handoffs",
+  "com_ui_agent_handoff_add": "Add handoff agent",
+  "com_ui_agent_handoff_description": "Handoff description",
+  "com_ui_agent_handoff_description_placeholder": "e.g., Transfer to data analyst for statistical analysis",
+  "com_ui_agent_handoff_info": "Configure agents that this agent can transfer conversations to when specific expertise is needed.",
+  "com_ui_agent_handoff_info_2": "Each handoff creates a transfer tool that enables seamless routing to specialist agents with context.",
+  "com_ui_agent_handoff_max": "Maximum {{0}} handoff agents reached.",
+  "com_ui_agent_handoff_prompt": "Passthrough content",
+  "com_ui_agent_handoff_prompt_placeholder": "Tell this agent what content to generate and pass to the handoff agent. You need to add something here to enable this feature",
+  "com_ui_agent_handoff_prompt_key": "Content parameter name (default: 'instructions')",
+  "com_ui_agent_handoff_prompt_key_placeholder": "Label the content passed (default: 'instructions')",
   "com_ui_agent_delete_error": "There was an error deleting the agent",
   "com_ui_agent_deleted": "Successfully deleted agent",
   "com_ui_agent_duplicate_error": "There was an error duplicating the agent",

packages/api/src/agents/validation.ts

@@ -38,6 +38,17 @@ export const agentSupportContactSchema = z
   })
   .optional();
 
+/** Graph edge schema for agent handoffs */
+export const graphEdgeSchema = z.object({
+  from: z.union([z.string(), z.array(z.string())]),
+  to: z.union([z.string(), z.array(z.string())]),
+  description: z.string().optional(),
+  edgeType: z.enum(['handoff', 'direct']).optional(),
+  prompt: z.union([z.string(), z.function()]).optional(),
+  excludeResults: z.boolean().optional(),
+  promptKey: z.string().optional(),
+});
+
 /** Base agent schema with all common fields */
 export const agentBaseSchema = z.object({
   name: z.string().nullable().optional(),
@@ -47,6 +58,7 @@ export const agentBaseSchema = z.object({
   model_parameters: z.record(z.unknown()).optional(),
   tools: z.array(z.string()).optional(),
   agent_ids: z.array(z.string()).optional(),
+  edges: z.array(graphEdgeSchema).optional(),
   end_after_tools: z.boolean().optional(),
   hide_sequential_outputs: z.boolean().optional(),
   artifacts: z.string().optional(),

packages/data-provider/src/schemas.ts

@@ -176,6 +176,7 @@ export const defaultAgentFormValues = {
   tools: [],
   provider: {},
   projectIds: [],
+  edges: [],
   artifacts: '',
   /** @deprecated Use ACL permissions instead */
   isCollaborative: false,

packages/data-provider/src/types/agents.ts

@@ -355,3 +355,45 @@ export type AgentToolType = {
 } & ({ assistant_id: string; agent_id?: never } | { assistant_id?: never; agent_id?: string });
 
 export type ToolMetadata = TPlugin;
+
+export interface BaseMessage {
+  content: string;
+  role?: string;
+  [key: string]: unknown;
+}
+
+export interface BaseGraphState {
+  [key: string]: unknown;
+}
+
+export type GraphEdge = {
+  /** Agent ID, use a list for multiple sources */
+  from: string | string[];
+  /** Agent ID, use a list for multiple destinations */
+  to: string | string[];
+  description?: string;
+  /** Can return boolean or specific destination(s) */
+  condition?: (state: BaseGraphState) => boolean | string | string[];
+  /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
+  edgeType?: 'handoff' | 'direct';
+  /**
+   * For direct 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,
+   * allowing the supervisor to pass specific instructions/context to the transferred agent.
+   */
+  prompt?: string | ((messages: BaseMessage[], runStartIndex: number) => string | undefined);
+  /**
+   * When true, excludes messages from startIndex when adding prompt.
+   * Automatically set to true when {results} variable is used in prompt.
+   */
+  excludeResults?: boolean;
+  /**
+   * For handoff edges: Customizes the parameter name for the handoff input.
+   * Defaults to "instructions" if not specified.
+   * Only applies when prompt is provided for handoff edges.
+   */
+  promptKey?: string;
+};

packages/data-provider/src/types/assistants.ts

@@ -1,7 +1,7 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import type { AssistantsEndpoint, AgentProvider } from 'src/schemas';
+import type { Agents, GraphEdge } from './agents';
 import type { ContentTypes } from './runs';
-import type { Agents } from './agents';
 import type { TFile } from './files';
 import { ArtifactModes } from 'src/artifacts';
 
@@ -226,6 +226,7 @@ export type Agent = {
   isCollaborative?: boolean;
   tool_resources?: AgentToolResources;
   agent_ids?: string[];
+  edges?: GraphEdge[];
   end_after_tools?: boolean;
   hide_sequential_outputs?: boolean;
   artifacts?: ArtifactModes;
@@ -251,6 +252,7 @@ export type AgentCreateParams = {
 } & Pick<
   Agent,
   | 'agent_ids'
+  | 'edges'
   | 'end_after_tools'
   | 'hide_sequential_outputs'
   | 'artifacts'
@@ -276,6 +278,7 @@ export type AgentUpdateParams = {
 } & Pick<
   Agent,
   | 'agent_ids'
+  | 'edges'
   | 'end_after_tools'
   | 'hide_sequential_outputs'
   | 'artifacts'

packages/data-schemas/src/schema/agent.ts

@@ -71,6 +71,10 @@ const agentSchema = new Schema<IAgent>(
     agent_ids: {
       type: [String],
     },
+    edges: {
+      type: [{ type: Schema.Types.Mixed }],
+      default: [],
+    },
     isCollaborative: {
       type: Boolean,
       default: undefined,

packages/data-schemas/src/types/agent.ts

@@ -1,4 +1,5 @@
 import { Document, Types } from 'mongoose';
+import type { GraphEdge } from 'librechat-data-provider';
 
 export interface ISupportContact {
   name?: string;
@@ -28,6 +29,7 @@ export interface IAgent extends Omit<Document, 'model'> {
   hide_sequential_outputs?: boolean;
   end_after_tools?: boolean;
   agent_ids?: string[];
+  edges?: GraphEdge[];
   /** @deprecated Use ACL permissions instead */
   isCollaborative?: boolean;
   conversation_starters?: string[];