Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

👯 fix: Separate Subagents and Handoffs Into Native Tools (#16761)

lia-by-librechat[bot]a4f6763b070c
diff --git a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx
index 2f9abe47b4..c76db6b09e 100644
--- a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx
+++ b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx
@@ -1,59 +1,46 @@
-import { useMemo } from 'react';
-import { useFormContext, Controller } from 'react-hook-form';
+import { Controller, useFormContext } from 'react-hook-form';
import { AgentCapabilities, MAX_SUBAGENTS } from 'librechat-data-provider';
import type { AgentForm } from '~/common';
import { useAgentPanelContext } from '~/Providers';
import AgentSubagents from './AgentSubagents';
import AgentHandoffs from './AgentHandoffs';
-import { groupHeadingClass } from './ui';
-import { useLocalize } from '~/hooks';
interface OrchestrationHubProps {
currentAgentId: string;
+ tool: 'subagents' | 'handoffs';
}
-/**
- * Settings for the native orchestration tool. Handoffs are always available.
- */
-export default function OrchestrationHub({ currentAgentId }: OrchestrationHubProps) {
- const localize = useLocalize();
+/** Settings for one native collaboration tool, never the other tool's fields. */
+export default function OrchestrationHub({ currentAgentId, tool }: OrchestrationHubProps) {
const { control } = useFormContext<AgentForm>();
const { agentsConfig } = useAgentPanelContext();
- const subagentsEnabled = useMemo(
- () => agentsConfig?.capabilities.includes(AgentCapabilities.subagents) ?? false,
- [agentsConfig],
- );
- const maxSubagents = agentsConfig?.maxSubagents ?? MAX_SUBAGENTS;
-
- return (
- <section className="flex flex-col gap-1">
- <div className="flex flex-col gap-0.5">
- <span className={groupHeadingClass}>{localize('com_ui_agent_orchestration')}</span>
- <p className="text-text-secondary text-xs">{localize('com_ui_agent_orchestration_hint')}</p>
- </div>
- <div className="divide-border-light divide-y">
- {subagentsEnabled && (
- <Controller
- name="subagents"
- control={control}
- render={({ field }) => (
- <AgentSubagents
- field={field}
- currentAgentId={currentAgentId}
- maxSubagents={maxSubagents}
- fileSharingEnabled={agentsConfig?.fileSharing?.enabled === true}
- />
- )}
+ if (tool === 'subagents') {
+ if (!agentsConfig?.capabilities.includes(AgentCapabilities.subagents)) {
+ return null;
+ }
+ return (
+ <Controller
+ name="subagents"
+ control={control}
+ render={({ field }) => (
+ <AgentSubagents
+ field={field}
+ currentAgentId={currentAgentId}
+ maxSubagents={agentsConfig.maxSubagents ?? MAX_SUBAGENTS}
+ fileSharingEnabled={agentsConfig.fileSharing?.enabled === true}
/>
)}
- <Controller
- name="edges"
- control={control}
- defaultValue={[]}
- render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}
- />
- </div>
- </section>
+ />
+ );
+ }
+
+ return (
+ <Controller
+ name="edges"
+ control={control}
+ defaultValue={[]}
+ render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}
+ />
);
}
diff --git a/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx b/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx
new file mode 100644
index 0000000000..ddad60ced6
--- /dev/null
+++ b/client/src/components/SidePanel/Agents/Advanced/__tests__/OrchestrationHub.spec.tsx
@@ -0,0 +1,69 @@
+import { useForm, FormProvider } from 'react-hook-form';
+import { fireEvent, render, screen } from '@testing-library/react';
+import type { UseFormReturn } from 'react-hook-form';
+import type { AgentForm } from '~/common';
+import OrchestrationHub from '../OrchestrationHub';
+
+let mockCapabilities = ['subagents'];
+let mockGetValues: UseFormReturn<AgentForm>['getValues'];
+jest.mock('~/hooks', () => ({ useLocalize: () => (key: string) => key }));
+jest.mock('~/Providers', () => ({
+ useAgentPanelContext: () => ({
+ agentsConfig: {
+ capabilities: mockCapabilities,
+ maxSubagents: 3,
+ fileSharing: { enabled: true },
+ },
+ }),
+ useAgentsMapContext: () => ({}),
+}));
+
+function Harness({ tool }: { tool: 'subagents' | 'handoffs' }) {
+ const methods = useForm<AgentForm>({
+ defaultValues: {
+ subagents: { enabled: true, allowSelf: false, agent_ids: [], shareFiles: true },
+ edges: [{ from: 'parent', to: 'child' }],
+ },
+ });
+ mockGetValues = methods.getValues;
+ return (
+ <FormProvider {...methods}>
+ <OrchestrationHub tool={tool} currentAgentId="parent" />
+ </FormProvider>
+ );
+}
+
+beforeEach(() => {
+ mockCapabilities = ['subagents'];
+});
+
+test('the subagent dialog exposes only subagent settings and preserves handoffs', () => {
+ render(<Harness tool="subagents" />);
+ expect(screen.getByRole('region', { name: 'com_ui_agent_subagents' })).toBeVisible();
+ expect(screen.queryByRole('region', { name: 'com_ui_agent_handoffs' })).not.toBeInTheDocument();
+ expect(screen.getByText('0 / 3')).toBeInTheDocument();
+ expect(screen.getByRole('switch', { name: 'com_ui_agent_subagents_share_files' })).toBeChecked();
+ const edges = mockGetValues('edges');
+ fireEvent.click(screen.getByRole('switch', { name: 'com_ui_agent_subagents_enable' }));
+ expect(mockGetValues('subagents.enabled')).toBe(false);
+ expect(mockGetValues('edges')).toEqual(edges);
+});
+
+test('the handoff dialog exposes only destination settings and preserves subagents', () => {
+ render(<Harness tool="handoffs" />);
+ expect(screen.getByRole('region', { name: 'com_ui_agent_handoffs' })).toBeVisible();
+ expect(screen.queryByRole('region', { name: 'com_ui_agent_subagents' })).not.toBeInTheDocument();
+ const subagents = mockGetValues('subagents');
+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_agent_handoff_remove' }));
+ expect(mockGetValues('edges')).toEqual([]);
+ expect(mockGetValues('subagents')).toEqual(subagents);
+});
+
+test('the capability gate suppresses subagents but not handoffs', () => {
+ mockCapabilities = [];
+ const { unmount } = render(<Harness tool="subagents" />);
+ expect(screen.queryByRole('region')).not.toBeInTheDocument();
+ unmount();
+ render(<Harness tool="handoffs" />);
+ expect(screen.getByRole('region', { name: 'com_ui_agent_handoffs' })).toBeVisible();
+});
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx
index 9eac7bc824..4582f07bab 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx
@@ -14,7 +14,8 @@ interface Props {
export default function ItemDialog({ item, agentId, onClose }: Props) {
const [portalElement, setPortalElement] = useState<HTMLDivElement | null>(null);
- const isOrchestration = item?.kind === 'builtin' && item.id === 'orchestration';
+ const isOrchestration =
+ item?.kind === 'builtin' && (item.id === 'subagents' || item.id === 'handoffs');
const isAction = item?.kind === 'action';
return (
<OGDialog open={item !== null} onOpenChange={(next) => !next && onClose()}>
diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx
index e0ee7c2af8..d8f3d63ee0 100644
--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx
@@ -143,8 +143,8 @@ export default function BuiltinSection({
let body: React.ReactNode = null;
- if (builtinId === 'orchestration') {
- body = <OrchestrationHub currentAgentId={agentId} />;
+ if (builtinId === 'subagents' || builtinId === 'handoffs') {
+ body = <OrchestrationHub currentAgentId={agentId} tool={builtinId} />;
} else if (builtinId === 'execute_code') {
body = (
<div className="flex flex-col gap-4">
@@ -176,7 +176,9 @@ export default function BuiltinSection({
}
const localizedDescription =
- description && builtinId !== 'orchestration' ? localize(description as TranslationKeys) : '';
+ description && builtinId !== 'subagents' && builtinId !== 'handoffs'
+ ? localize(description as TranslationKeys)
+ : '';
return (
<div className="flex flex-col gap-5">
diff --git a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx
index 83b79998eb..b4d89e9043 100644
--- a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx
@@ -23,9 +23,9 @@ import {
} from './items/selectors';
import { useAgentFileEntries, useAgentItems, useUninstallToolCredentials } from './hooks';
import MarketplaceSidebar, { MarketplaceFilterBar } from './MarketplaceSidebar';
+import { setSubagentsEnabled, removeHandoffs } from './items/orchestration';
import { requiresFileManagerRemoval } from './items/capabilities';
import AddMcpServerDialog from './ItemDialog/AddMcpServerDialog';
-import { removeOrchestration } from './items/orchestration';
import { computeToggleAction } from './items/mutations';
import { useLocalize, useToolFavorites } from '~/hooks';
import MarketplaceCatalog from './MarketplaceCatalog';
@@ -131,14 +131,14 @@ export default function ToolsMarketplaceDialog({
case 'configure':
setDetailItem(item);
break;
- case 'orchestration-remove': {
- const next = removeOrchestration(getValues('subagents'), getValues('edges'));
- if (next.subagents) {
- setValue('subagents', next.subagents, { shouldDirty: true });
- }
- setValue('edges', next.edges, { shouldDirty: true });
+ case 'subagents':
+ setValue('subagents', setSubagentsEnabled(getValues('subagents'), patch.enabled), {
+ shouldDirty: true,
+ });
+ break;
+ case 'handoffs-remove':
+ setValue('edges', removeHandoffs(getValues('edges')), { shouldDirty: true });
break;
- }
case 'builtin':
setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });
if (patch.field === AgentCapabilities.execute_code && patch.value === false) {
diff --git a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx
index 1885ae0548..2d3c2cc44e 100644
--- a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx
@@ -21,10 +21,10 @@ import {
useUninstallToolCredentials,
} from './hooks';
import { useSkillsInfiniteQuery, useDeleteAgentAction } from '~/data-provider';
+import { setSubagentsEnabled, removeHandoffs } from './items/orchestration';
import { requiresFileManagerRemoval } from './items/capabilities';
import { useRemoveMCPTool, useVisibleTools } from '~/hooks/MCP';
import ToolsMarketplaceDialog from './ToolsMarketplaceDialog';
-import { removeOrchestration } from './items/orchestration';
import { computeToggleAction } from './items/mutations';
import { useLocalize, useHasAccess } from '~/hooks';
import { useAgentPanelContext } from '~/Providers';
@@ -128,14 +128,14 @@ export default function ToolsSection({ agentId }: Props) {
case 'configure':
setDialogItem(item);
break;
- case 'orchestration-remove': {
- const next = removeOrchestration(getValues('subagents'), getValues('edges'));
- if (next.subagents) {
- setValue('subagents', next.subagents, { shouldDirty: true });
- }
- setValue('edges', next.edges, { shouldDirty: true });
+ case 'subagents':
+ setValue('subagents', setSubagentsEnabled(getValues('subagents'), patch.enabled), {
+ shouldDirty: true,
+ });
+ break;
+ case 'handoffs-remove':
+ setValue('edges', removeHandoffs(getValues('edges')), { shouldDirty: true });
break;
- }
case 'builtin':
setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });
if (patch.field === AgentCapabilities.execute_code && patch.value === false) {
diff --git a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx
index 0ddb103916..bc6aa93af1 100644
--- a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsMarketplaceDialog.spec.tsx
@@ -9,6 +9,8 @@ let mockWatchedTools: string[] = [];
let mockExecuteCode = false;
let mockMcpServersMap = new Map<string, object>();
let mockIsDesktop = true;
+let mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };
+let mockEdges: Array<{ from: string; to: string; edgeType?: 'handoff' | 'direct' }> = [];
jest.mock('react-hook-form', () => ({
useFormContext: () => ({
@@ -18,6 +20,8 @@ jest.mock('react-hook-form', () => ({
}),
useWatch: ({ name }: { name: string }) => {
const map: Record<string, unknown> = {
+ subagents: mockSubagents,
+ edges: mockEdges,
tools: mockWatchedTools,
skills: [],
execute_code: mockExecuteCode,
@@ -34,7 +38,7 @@ jest.mock('react-hook-form', () => ({
jest.mock('~/Providers', () => ({
useAgentPanelContext: () => ({
- agentsConfig: { capabilities: ['execute_code', 'tools'] },
+ agentsConfig: { capabilities: ['execute_code', 'tools', 'subagents'] },
regularTools: [{ pluginKey: 'dalle', name: 'DALL-E', description: 'Images' }],
mcpServersMap: mockMcpServersMap,
actions: [],
@@ -102,6 +106,8 @@ jest.mock('../hooks', () => {
});
const selected = deriveSelectedItems(
{
+ subagents: useWatch({ name: 'subagents' }),
+ edges: useWatch({ name: 'edges' }),
execute_code: (useWatch({ name: 'execute_code' }) ?? false) as boolean,
web_search: (useWatch({ name: 'web_search' }) ?? false) as boolean,
file_search: (useWatch({ name: 'file_search' }) ?? false) as boolean,
@@ -173,6 +179,8 @@ describe('ToolsMarketplaceDialog', () => {
mockToggleFavorite.mockClear();
mockFavoriteKeys = new Set<string>();
mockIsDesktop = true;
+ mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };
+ mockEdges = [];
mockFileEntries = { contextFiles: [], knowledgeFiles: [], codeFiles: [] };
});
@@ -410,3 +418,54 @@ describe('ToolsMarketplaceDialog', () => {
expect(screen.getByText('com_ui_tools_view_favorites_empty')).toBeInTheDocument();
});
});
+
+describe('native collaboration tools', () => {
+ beforeEach(() => {
+ mockSetValue.mockClear();
+ mockGetValues.mockReset();
+ mockGetValues.mockReturnValue([]);
+ mockSubagents = { enabled: false, allowSelf: false, agent_ids: ['reviewer'] };
+ mockEdges = [];
+ });
+
+ test.each(['subagents', 'handoffs'] as const)(
+ 'the marketplace removes %s independently',
+ (id) => {
+ mockSubagents = { enabled: true, allowSelf: false, agent_ids: ['reviewer'] };
+ mockEdges = [
+ { from: 'parent', to: 'reviewer' },
+ { from: 'parent', to: 'other', edgeType: 'direct' },
+ ];
+ mockGetValues.mockImplementation((name: string) =>
+ name === 'subagents' ? mockSubagents : mockEdges,
+ );
+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);
+ fireEvent.click(
+ screen.getByRole('button', {
+ name: new RegExp(id === 'subagents' ? 'com_ui_agent_subagents' : 'com_ui_agent_handoffs'),
+ }),
+ );
+ expect(mockSetValue.mock.calls).toEqual(
+ id === 'subagents'
+ ? [['subagents', { ...mockSubagents, enabled: false }, { shouldDirty: true }]]
+ : [['edges', [mockEdges[1]], { shouldDirty: true }]],
+ );
+ },
+ );
+
+ test('adding subagents enables the retained configuration without touching handoffs', () => {
+ mockGetValues.mockImplementation(() => mockSubagents);
+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);
+ fireEvent.click(screen.getByRole('button', { name: /com_ui_agent_subagents/ }));
+ expect(mockSetValue.mock.calls).toEqual([
+ ['subagents', { ...mockSubagents, enabled: true }, { shouldDirty: true }],
+ ]);
+ });
+
+ test('adding handoffs opens only their destination dialog without mutating the form', () => {
+ render(<ToolsMarketplaceDialog open onOpenChange={jest.fn()} agentId="a1" />);
+ fireEvent.click(screen.getByRole('button', { name: /com_ui_agent_handoffs/ }));
+ expect(screen.getByTestId('item-dialog')).toBeInTheDocument();
+ expect(mockSetValue).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx
index cf7a6bef04..d4226ad31e 100644
--- a/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx
+++ b/client/src/components/SidePanel/Agents/Tools/__tests__/ToolsSection.spec.tsx
@@ -304,3 +304,26 @@ describe('ToolsSection', () => {
);
});
});
+
+test.each(['subagents', 'handoffs'] as const)(
+ 'removing %s only writes that tool’s fields',
+ (id) => {
+ mockSelected = [{ kind: 'builtin', id, name: '', description: '', iconKey: id }];
+ const subagents = {
+ enabled: true,
+ allowSelf: false,
+ shareFiles: true,
+ agent_ids: ['reviewer'],
+ };
+ const handoff = { from: 'parent', to: 'reviewer' };
+ const direct = { from: 'parent', to: ['left', 'right'] };
+ mockFormValues = { subagents, edges: [handoff, direct] };
+ render(<ToolsSection agentId="a" />);
+ fireEvent.click(screen.getByRole('button', { name: `remove-${id}` }));
+ expect(mockSetValue.mock.calls).toEqual(
+ id === 'subagents'
+ ? [['subagents', { ...subagents, enabled: false }, { shouldDirty: true }]]
+ : [['edges', [direct], { shouldDirty: true }]],
+ );
+ },
+);
diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts
index b3d57ff719..a131a52241 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts
@@ -23,8 +23,8 @@ const askInputs: BuildCatalogInputs = {
};
describe('buildCatalog', () => {
- test('offers orchestration for always-available handoffs without the subagents capability', () => {
- expect(buildCatalog(emptyInputs).map((item) => item.id)).toEqual(['orchestration']);
+ test('offers handoffs without the subagents capability', () => {
+ expect(buildCatalog(emptyInputs).map((item) => item.id)).toEqual(['handoffs']);
});
test('emits built-in items only for capabilities the admin enabled', () => {
@@ -35,18 +35,19 @@ describe('buildCatalog', () => {
},
});
expect(items.filter((i) => i.kind === 'builtin').map((i) => i.id)).toEqual([
- 'orchestration',
+ 'handoffs',
AgentCapabilities.execute_code,
AgentCapabilities.web_search,
]);
});
- test('offers exactly one orchestration item when subagents are enabled', () => {
+ test('offers two separate native tools when subagents are enabled', () => {
const items = buildCatalog({
...emptyInputs,
agentsConfig: { capabilities: [AgentCapabilities.subagents] },
});
- expect(items.map((item) => item.id)).toEqual(['orchestration']);
+ expect(items.map((item) => item.id)).toEqual(['subagents', 'handoffs']);
+ expect(items.map((item) => item.kind)).toEqual(['builtin', 'builtin']);
});
test('emits the memory builtin only when showMemory is set', () => {
diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts
index ff83f2a477..26dfbb1fc3 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts
@@ -1,18 +1,26 @@
import type { AgentSubagentsConfig, GraphEdge } from 'librechat-data-provider';
import type { FormSelection } from '../selectors';
import type { AgentItem } from '../types';
-import { isHandoffEdge, removeOrchestration } from '../orchestration';
+import { isHandoffEdge, setSubagentsEnabled, removeHandoffs } from '../orchestration';
import { hasConfigurableSettings } from '../configurable';
import { deriveSelectedItems } from '../selectors';
import { computeToggleAction } from '../mutations';
-const item: AgentItem = {
+const subagentItem: AgentItem = {
kind: 'builtin',
- id: 'orchestration',
+ id: 'subagents',
name: '',
description: '',
- iconKey: 'orchestration',
+ iconKey: 'subagents',
};
+const handoffItem: AgentItem = {
+ kind: 'builtin',
+ id: 'handoffs',
+ name: '',
+ description: '',
+ iconKey: 'handoffs',
+};
+const catalog = [subagentItem, handoffItem];
const form: FormSelection = {
execute_code: false,
web_search: false,
@@ -33,28 +41,40 @@ const handoff: GraphEdge = {
};
const direct: GraphEdge = { from: 'parent', to: 'other', edgeType: 'direct' };
-test('derives the native item from existing subagent and handoff configurations', () => {
- expect(deriveSelectedItems(form, [item], [])).toEqual([]);
- expect(deriveSelectedItems({ ...form, subagents: { enabled: true } }, [item], [])).toEqual([
- item,
+test('derives each native tool independently from stored configuration', () => {
+ expect(deriveSelectedItems(form, catalog, [])).toEqual([]);
+ expect(deriveSelectedItems({ ...form, subagents: { enabled: true } }, catalog, [])).toEqual([
+ subagentItem,
]);
- expect(deriveSelectedItems({ ...form, edges: [handoff] }, [item], [])).toEqual([item]);
+ expect(deriveSelectedItems({ ...form, edges: [handoff] }, catalog, [])).toEqual([handoffItem]);
+ expect(
+ deriveSelectedItems({ ...form, subagents: { enabled: true }, edges: [handoff] }, catalog, []),
+ ).toEqual(catalog);
expect(
deriveSelectedItems(
{ ...form, edges: [direct], subagents: { enabled: false, agent_ids: ['child'] } },
- [item],
+ catalog,
[],
),
).toEqual([]);
});
-test('adding opens settings instead of writing a bogus capability or plugin', () => {
- expect(computeToggleAction(item, { selected: false })).toEqual({ type: 'configure' });
- expect(computeToggleAction(item, { selected: true })).toEqual({ type: 'orchestration-remove' });
- expect(hasConfigurableSettings(item)).toBe(true);
+test('toggles subagents and opens destination settings to add handoffs', () => {
+ expect(computeToggleAction(subagentItem, { selected: false })).toEqual({
+ type: 'subagents',
+ enabled: true,
+ });
+ expect(computeToggleAction(subagentItem, { selected: true })).toEqual({
+ type: 'subagents',
+ enabled: false,
+ });
+ expect(computeToggleAction(handoffItem, { selected: false })).toEqual({ type: 'configure' });
+ expect(computeToggleAction(handoffItem, { selected: true })).toEqual({ type: 'handoffs-remove' });
+ expect(hasConfigurableSettings(subagentItem)).toBe(true);
+ expect(hasConfigurableSettings(handoffItem)).toBe(true);
});
-test('removal explicitly disables subagents and preserves their settings and unrelated edges', () => {
+test('subagent toggles preserve their complete settings and restore the retained roster', () => {
const subagents: AgentSubagentsConfig = {
enabled: true,
allowSelf: false,
@@ -72,12 +92,15 @@ test('removal explicitly disables subagents and preserves their settings and unr
},
],
};
- expect(removeOrchestration(subagents, [handoff, direct])).toEqual({
- subagents: { ...subagents, enabled: false },
- edges: [direct],
- });
+ const disabled = setSubagentsEnabled(subagents, false);
+ expect(disabled).toEqual({ ...subagents, enabled: false });
expect(subagents.enabled).toBe(true);
- expect(removeOrchestration(undefined, [handoff])).toEqual({ subagents: undefined, edges: [] });
+ expect(setSubagentsEnabled(disabled, true)).toEqual(subagents);
+ expect(setSubagentsEnabled(undefined, true)).toEqual({
+ enabled: true,
+ allowSelf: true,
+ agent_ids: [],
+ });
});
test.each<[GraphEdge, boolean]>([
@@ -90,8 +113,16 @@ test.each<[GraphEdge, boolean]>([
[{ from: 'parent', to: 'child', edgeType: 'direct' }, false],
])('matches runtime classification for %j', (edge, expected) => {
expect(isHandoffEdge(edge)).toBe(expected);
- expect(deriveSelectedItems({ ...form, edges: [edge] }, [item], [])).toEqual(
- expected ? [item] : [],
+ expect(deriveSelectedItems({ ...form, edges: [edge] }, [handoffItem], [])).toEqual(
+ expected ? [handoffItem] : [],
);
- expect(removeOrchestration(undefined, [edge]).edges).toEqual(expected ? [] : [edge]);
+ expect(removeHandoffs([edge])).toEqual(expected ? [] : [edge]);
+});
+
+test('handoff removal retains all direct edges and does not mutate stored input', () => {
+ const implicitDirect: GraphEdge = { from: 'parent', to: ['left', 'right'] };
+ const edges = [handoff, direct, implicitDirect];
+ expect(removeHandoffs(edges)).toEqual([direct, implicitDirect]);
+ expect(edges).toHaveLength(3);
+ expect(removeHandoffs()).toEqual([]);
});
diff --git a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts b/client/src/components/SidePanel/Agents/Tools/items/catalog.ts
index e7b5c633ac..0b2b62e593 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/catalog.ts
@@ -122,14 +122,23 @@ export function buildCatalog(inputs: BuildCatalogInputs): AgentItem[] {
const items: AgentItem[] = [
{
kind: 'builtin',
- id: 'orchestration',
- iconKey: 'orchestration',
- name: 'com_ui_agent_orchestration',
- description: 'com_ui_agent_orchestration_hint',
+ id: 'handoffs',
+ iconKey: 'handoffs',
+ name: 'com_ui_agent_handoffs',
+ description: 'com_ui_agent_handoffs_subtitle',
},
];
const enabled = new Set(inputs.agentsConfig.capabilities);
+ if (enabled.has(AgentCapabilities.subagents)) {
+ items.unshift({
+ kind: 'builtin',
+ id: AgentCapabilities.subagents,
+ iconKey: 'subagents',
+ name: 'com_ui_agent_subagents',
+ description: 'com_ui_agent_subagents_subtitle',
+ });
+ }
for (const def of BUILTIN_DEFINITIONS) {
if (!enabled.has(def.id)) {
continue;
diff --git a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts b/client/src/components/SidePanel/Agents/Tools/items/configurable.ts
index b3e4f6a7a6..7e4662bc86 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/configurable.ts
@@ -16,7 +16,8 @@ export function hasConfigurableSettings(item: AgentItem): boolean {
item.id === 'file_search' ||
item.id === 'context' ||
item.id === 'memory' ||
- item.id === 'orchestration' ||
+ item.id === 'subagents' ||
+ item.id === 'handoffs' ||
(item.id === 'web_search' && item.userProvidedAuth === true)
);
case 'tool':
diff --git a/client/src/components/SidePanel/Agents/Tools/items/icons.ts b/client/src/components/SidePanel/Agents/Tools/items/icons.ts
index 1e75d7049e..3ddd5461c5 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/icons.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/icons.ts
@@ -12,6 +12,7 @@ import {
Zap,
Layers,
Network,
+ Waypoints,
} from 'lucide-react';
import type { LucideIcon } from 'lucide-react';
import type { AgentItem } from './types';
@@ -23,10 +24,14 @@ export interface ItemIcon {
}
const BUILTIN_ICONS: Record<string, ItemIcon> = {
- orchestration: {
+ subagents: {
Icon: Network,
colorClass: 'bg-series-2/15 text-series-2',
},
+ handoffs: {
+ Icon: Waypoints,
+ colorClass: 'bg-series-4/15 text-series-4',
+ },
execute_code: {
Icon: Code,
colorClass: 'bg-series-7/15 text-series-7',
diff --git a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts b/client/src/components/SidePanel/Agents/Tools/items/mutations.ts
index e79206f84d..f7debe7dc4 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/mutations.ts
@@ -3,7 +3,8 @@ import type { AgentItem } from './types';
export type TogglePatch =
| { type: 'builtin'; field: AgentCapabilities; value: boolean | string }
- | { type: 'orchestration-remove' }
+ | { type: 'subagents'; enabled: boolean }
+ | { type: 'handoffs-remove' }
| { type: 'configure' }
| { type: 'tool-add'; id: string }
| { type: 'tool-remove'; id: string }
@@ -15,8 +16,11 @@ export type TogglePatch =
| { type: 'action-remove'; actionId: string };
function builtinTogglePatch(id: string, selected: boolean): TogglePatch {
- if (id === 'orchestration') {
- return selected ? { type: 'orchestration-remove' } : { type: 'configure' };
+ if (id === 'subagents') {
+ return { type: 'subagents', enabled: !selected };
+ }
+ if (id === 'handoffs') {
+ return selected ? { type: 'handoffs-remove' } : { type: 'configure' };
}
if (id === 'ask_user_question') {
// Native tool presented as a builtin — it has no capability field; the
diff --git a/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts b/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts
index 232d176be9..1849ab27b7 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts
@@ -9,10 +9,20 @@ export function isHandoffEdge(edge: GraphEdge): boolean {
return edge.edgeType !== 'direct' && !defaultDirect;
}
-/** Disable orchestration without losing subagent settings or non-handoff edges. */
-export function removeOrchestration(subagents?: AgentSubagentsConfig, edges?: GraphEdge[]) {
+/** Persist the explicit flag while retaining the roster, graphs, and granular settings. */
+export function setSubagentsEnabled(
+ subagents: AgentSubagentsConfig | undefined,
+ enabled: boolean,
+): AgentSubagentsConfig {
return {
- subagents: subagents ? { ...subagents, enabled: false } : undefined,
- edges: (edges ?? []).filter((edge) => !isHandoffEdge(edge)),
+ ...subagents,
+ enabled,
+ allowSelf: subagents?.allowSelf ?? true,
+ agent_ids: subagents?.agent_ids ?? [],
};
}
+
+/** Removing handoffs must leave unrelated direct edges intact. */
+export function removeHandoffs(edges?: GraphEdge[]): GraphEdge[] {
+ return (edges ?? []).filter((edge) => !isHandoffEdge(edge));
+}
diff --git a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts b/client/src/components/SidePanel/Agents/Tools/items/selectors.ts
index d1186e095f..2735f490c9 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/selectors.ts
@@ -53,8 +53,10 @@ function isBuiltinSelected(item: AgentItem, form: FormSelection): boolean {
return Boolean(form.artifacts);
case 'context':
return form.context_files.length > 0;
- case 'orchestration':
- return form.subagents?.enabled === true || form.edges?.some(isHandoffEdge) === true;
+ case 'subagents':
+ return form.subagents?.enabled === true;
+ case 'handoffs':
+ return form.edges?.some(isHandoffEdge) === true;
case 'ask_user_question':
// Native tool presented as a builtin — selection lives in agent.tools.
return form.tools.includes('ask_user_question');
diff --git a/client/src/components/SidePanel/Agents/Tools/items/types.ts b/client/src/components/SidePanel/Agents/Tools/items/types.ts
index 7478c15064..43e0f1872c 100644
--- a/client/src/components/SidePanel/Agents/Tools/items/types.ts
+++ b/client/src/components/SidePanel/Agents/Tools/items/types.ts
@@ -22,7 +22,8 @@ export type BuiltinId =
* in `selectors.ts` / `mutations.ts`.
*/
| 'ask_user_question'
- | 'orchestration';
+ | `${AgentCapabilities.subagents}`
+ | 'handoffs';
export type AgentItemStatus = 'needs_setup';
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index b2e873d112..43ab38d6e6 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -1115,8 +1115,6 @@
"com_ui_agent_id_copy": "Copy agent ID",
"com_ui_agent_name": "Agent name",
"com_ui_agent_name_is_required": "Agent name is required",
- "com_ui_agent_orchestration": "Multi-agent orchestration",
- "com_ui_agent_orchestration_hint": "Choose how this agent works with other agents.",
"com_ui_agent_recursion_limit": "Max Agent Steps",
"com_ui_agent_recursion_limit_info": "Limits how many steps the agent can take in a run before giving a final response. Default is 25 steps. A step is either an AI API request or a tool usage round. For example, a basic tool interaction takes 3 steps: initial request, tool usage, and follow-up request.",
"com_ui_agent_subagents": "Subagents",
diff --git a/e2e/specs/mock/agent-collaboration-tools.spec.ts b/e2e/specs/mock/agent-collaboration-tools.spec.ts
new file mode 100644
index 0000000000..5b81d4bd84
--- /dev/null
+++ b/e2e/specs/mock/agent-collaboration-tools.spec.ts
@@ -0,0 +1,122 @@
+import { expect, test } from '@playwright/test';
+import type { Locator, Page } from '@playwright/test';
+import type { AgentDetail } from './agents.helpers';
+import { cleanupAgent, openAgentBuilder, uniqueAgentName } from './agents.helpers';
+import { MOCK_ENDPOINTS, fetchJson, getAccessToken, requestJson } from './helpers';
+
+const toolRow = (form: Locator, name: string) =>
+ form.getByRole('listitem').filter({ has: form.page().getByText(name, { exact: true }) });
+
+async function saveAgent(page: Page, form: Locator, agentId: string) {
+ const [response] = await Promise.all([
+ page.waitForResponse(
+ (candidate) =>
+ candidate.request().method() === 'PATCH' &&
+ new URL(candidate.url()).pathname === `/api/agents/${agentId}` &&
+ candidate.ok(),
+ ),
+ form.getByRole('button', { name: 'Save', exact: true }).click(),
+ ]);
+ expect(response.ok()).toBeTruthy();
+}
+
+test('subagents and handoffs have separate native tools, settings, and persistence', async ({
+ page,
+}) => {
+ test.setTimeout(90000);
+ await page.goto('/c/new');
+ const token = await getAccessToken(page);
+ const child = await requestJson<AgentDetail>(page, {
+ path: '/api/agents',
+ token,
+ method: 'POST',
+ body: {
+ name: uniqueAgentName('E2E Native Reviewer'),
+ provider: MOCK_ENDPOINTS[0].label,
+ model: MOCK_ENDPOINTS[0].model,
+ },
+ });
+ let parent: AgentDetail | undefined;
+ try {
+ parent = await requestJson<AgentDetail>(page, {
+ path: '/api/agents',
+ token,
+ method: 'POST',
+ body: {
+ name: uniqueAgentName('E2E Native Collaboration'),
+ provider: MOCK_ENDPOINTS[0].label,
+ model: MOCK_ENDPOINTS[0].model,
+ subagents: { enabled: true, allowSelf: false, agent_ids: [child.id] },
+ edges: [
+ { from: '', to: child.id },
+ { from: '', to: child.id, edgeType: 'direct' },
+ ],
+ },
+ });
+ const form = await openAgentBuilder(page);
+ await form.getByRole('combobox', { name: 'Agent', exact: true }).click();
+ await page.getByRole('option', { name: parent.name, exact: true }).click();
+ await expect(form.getByLabel('Agent name')).toHaveValue(parent.name ?? '');
+ const subagents = toolRow(form, 'Subagents');
+ const handoffs = toolRow(form, 'Handoffs');
+ await expect(subagents).toBeVisible();
+ await expect(handoffs).toBeVisible();
+ await expect(form.getByText('Multi-agent orchestration', { exact: true })).toHaveCount(0);
+
+ await subagents.getByRole('button', { name: 'Configure', exact: true }).click();
+ const dialog = page.getByTestId('item-dialog');
+ await expect(dialog.getByRole('region', { name: 'Subagents', exact: true })).toBeVisible();
+ await expect(dialog.getByRole('region', { name: 'Handoffs', exact: true })).toHaveCount(0);
+ await expect(
+ dialog.getByRole('switch', { name: 'Allow self-spawn', exact: true }),
+ ).not.toBeChecked();
+ await dialog.getByRole('button', { name: 'Close', exact: true }).click();
+ await expect(dialog).toBeHidden();
+
+ await handoffs.getByRole('button', { name: 'Configure', exact: true }).click();
+ await expect(dialog.getByRole('region', { name: 'Handoffs', exact: true })).toBeVisible();
+ await expect(dialog.getByRole('region', { name: 'Subagents', exact: true })).toHaveCount(0);
+ await dialog.getByRole('combobox', { name: 'Select agent', exact: true }).click();
+ const search = page.locator('input[placeholder="Search agent"]:visible');
+ await search.fill(child.name ?? '');
+ await expect(search).toBeFocused();
+ await expect(page.getByRole('option', { name: child.name, exact: true })).toBeVisible();
+ await page.keyboard.press('Escape');
+ await dialog.getByRole('button', { name: 'Close', exact: true }).click();
+ await expect(dialog).toBeHidden();
+
+ await subagents.getByRole('button', { name: 'Remove from agent', exact: true }).click();
+ await expect(subagents).toHaveCount(0);
+ await expect(handoffs).toBeVisible();
+ await saveAgent(page, form, parent.id);
+ let saved = await fetchJson<AgentDetail>(page, `/api/agents/${parent.id}/expanded`, token);
+ expect(saved.subagents).toEqual({ enabled: false, allowSelf: false, agent_ids: [child.id] });
+ expect(saved.edges).toEqual(parent.edges);
+
+ await form.getByRole('button', { name: 'Add tools', exact: true }).click();
+ const library = page.getByRole('dialog', { name: 'Tool Library', exact: true });
+ await library
+ .getByRole('button', { name: /^Subagents/ })
+ .first()
+ .click();
+ await library.getByRole('button', { name: 'Close', exact: true }).click();
+ await expect(subagents).toBeVisible();
+ await handoffs.getByRole('button', { name: 'Remove from agent', exact: true }).click();
+ await expect(handoffs).toHaveCount(0);
+ await expect(subagents).toBeVisible();
+ await saveAgent(page, form, parent.id);
+ saved = await fetchJson<AgentDetail>(page, `/api/agents/${parent.id}/expanded`, token);
+ expect(saved.subagents).toEqual({ enabled: true, allowSelf: false, agent_ids: [child.id] });
+ expect(saved.edges).toEqual(parent.edges?.filter((edge) => edge.edgeType === 'direct'));
+ await page.reload();
+ const reopened = await openAgentBuilder(page, { navigate: false });
+ await reopened.getByRole('combobox', { name: 'Agent', exact: true }).click();
+ await page.getByRole('option', { name: parent.name, exact: true }).click();
+ await expect(reopened.getByLabel('Agent name')).toHaveValue(parent.name ?? '');
+ await expect(toolRow(reopened, 'Subagents')).toBeVisible();
+ await expect(toolRow(reopened, 'Handoffs')).toHaveCount(0);
+ } finally {
+ await cleanupAgent(page, parent?.id);
+ await cleanupAgent(page, child.id);
+ }
+});
diff --git a/e2e/specs/mock/agent-handoffs.spec.ts b/e2e/specs/mock/agent-handoffs.spec.ts
index a0e1b427f7..a450c25e3b 100644
--- a/e2e/specs/mock/agent-handoffs.spec.ts
+++ b/e2e/specs/mock/agent-handoffs.spec.ts
@@ -68,7 +68,7 @@ async function waitForMCPTool(page: Page, token: string): Promise<void> {
async function openOrchestration(page: Page, form: Locator) {
const settings = form
.getByRole('listitem')
- .filter({ hasText: 'Multi-agent orchestration' })
+ .filter({ hasText: 'Handoffs' })
.getByRole('button', { name: 'Configure', exact: true });
if (await settings.count()) {
await settings.click();
@@ -77,7 +77,7 @@ async function openOrchestration(page: Page, form: Locator) {
await page
.getByRole('dialog', { name: 'Tool Library', exact: true })
.getByRole('listitem')
- .filter({ hasText: 'Multi-agent orchestration' })
+ .filter({ hasText: 'Handoffs' })
.getByRole('button', { name: 'Configure', exact: true })
.click();
}