👯 fix: Separate Subagents and Handoffs Into Native Tools (#16761)
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Sync Locize Translations & Create Translation PR / Sync Translation Keys with Locize (push) Waiting to run
Sync Locize Translations & Create Translation PR / Create Translation PR on Version Published (push) Blocked by required conditions

* fix: separate subagents and handoffs into native tools

* test: reselect the saved agent after browser reload

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-10-04 22:55:13 -04:00 • committed by GitHub
parent 50dbc0dbb8
commit a4f6763b07
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 436 additions and 111 deletions

View file

@ -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} />}
/>
);
}

View file

@ -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();
});

View file

@ -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()}>

View file

@ -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">

View file

@ -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) {

View file

@ -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) {

View file

@ -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();
});
});

View file

@ -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 }]],
);
},
);

View file

@ -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', () => {

View file

@ -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([]);
});

View file

@ -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;

View file

@ -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':

View file

@ -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',

View file

@ -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

View file

@ -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));
}

View file

@ -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');

View file

@ -22,7 +22,8 @@ export type BuiltinId =
* in `selectors.ts` / `mutations.ts`.
*/
| 'ask_user_question'
| 'orchestration';
| `${AgentCapabilities.subagents}`
| 'handoffs';
export type AgentItemStatus = 'needs_setup';

View file

@ -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",

View file

@ -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);
}
});

View file

@ -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();
}