Andreas/LibreChat
1
0
Fork 0
mirror of https://github.com/danny-avila/LibreChat.git synced 2026-01-11 13:08:51 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

feat: add per-tool configuration options for agents, including deferred loading and allowed callers

Browse source 
- Introduced `tool_options` in agent forms to manage tool behavior.
- Updated tool classification logic to prioritize agent-level configurations.
- Enhanced UI components to support tool deferral functionality.
- Added localization strings for new tool options and actions.
This commit is contained in:
Danny Avila 2026-01-07 20:16:15 -05:00
parent fff9cecad2
commit 4682f0e370
No known key found for this signature in database
GPG key ID: BF31EEB2C5CA0956
9 changed files with 388 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

1
api/server/services/ToolService.js
View file

@ -522,6 +522,7 @@ async function loadAgentTools({
loadedTools,
userId: req.user.id,
agentId: agent.id,
agentToolOptions: agent.tool_options,
loadAuthValues,
});
agentTools.push(...additionalTools);

3
client/src/common/agents-types.ts
View file

@ -1,6 +1,7 @@
import { AgentCapabilities, ArtifactModes } from 'librechat-data-provider';
import type {
AgentModelParameters,
AgentToolOptions,
SupportContact,
AgentProvider,
GraphEdge,
@ -33,6 +34,8 @@ export type AgentForm = {
model: string | null;
model_parameters: AgentModelParameters;
tools?: string[];
/** Per-tool configuration options (deferred loading, allowed callers, etc.) */
tool_options?: AgentToolOptions;
provider?: AgentProvider | OptionWithIcon;
/** @deprecated Use edges instead */
agent_ids?: string[];

9
client/src/components/SidePanel/Agents/AgentPanel.tsx
View file

@ -23,6 +23,7 @@ import {
import { createProviderOption, getDefaultAgentFormValues } from '~/utils';
import { useResourcePermissions } from '~/hooks/useResourcePermissions';
import { useSelectAgent, useLocalize, useAuthContext } from '~/hooks';
import type { TranslationKeys } from '~/hooks/useLocalize';
import { useAgentPanelContext } from '~/Providers/AgentPanelContext';
import AgentPanelSkeleton from './AgentPanelSkeleton';
import AdvancedPanel from './Advanced/AdvancedPanel';
@ -36,8 +37,8 @@ import ModelPanel from './ModelPanel';
function getUpdateToastMessage(
noVersionChange: boolean,
avatarActionState: AgentForm['avatar_action'],
name: string | undefined,
localize: (key: string, vars?: Record<string, unknown> | Array<string | number>) => string,
name: string | null | undefined,
localize: (key: TranslationKeys, vars?: Record<string, unknown>) => string,
): string | null {
// If only avatar upload is pending (separate endpoint), suppress the no-changes toast.
if (noVersionChange && avatarActionState === 'upload') {
@ -72,6 +73,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
recursion_limit,
category,
support_contact,
tool_options,
avatar_action: avatarActionState,
} = data;
@ -97,6 +99,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
recursion_limit,
category,
support_contact,
tool_options,
...(shouldResetAvatar ? { avatar: null } : {}),
},
provider,
@ -545,7 +548,7 @@ export default function AgentPanel() {
<AgentFooter
createMutation={create}
updateMutation={update}
isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isPending}
isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isLoading}
activePanel={activePanel}
setActivePanel={setActivePanel}
setCurrentAgentId={setCurrentAgentId}

5
client/src/components/SidePanel/Agents/AgentSelect.tsx
View file

@ -111,6 +111,11 @@ export default function AgentSelect({
return;
}
if (name === 'tool_options' && typeof value === 'object' && value !== null) {
formValues[name] = value;
return;
}
if (!keys.has(name)) {
return;
}

290
client/src/components/SidePanel/Agents/MCPTool.tsx
View file

@ -1,8 +1,9 @@
import React, { useState } from 'react';
import { ChevronDown } from 'lucide-react';
import { useFormContext } from 'react-hook-form';
import React, { useState, useCallback, useEffect } from 'react';
import { ChevronDown, Clock } from 'lucide-react';
import { useFormContext, useWatch } from 'react-hook-form';
import { Constants } from 'librechat-data-provider';
import * as AccordionPrimitive from '@radix-ui/react-accordion';
import type { AgentToolOptions } from 'librechat-data-provider';
import {
Label,
ESide,
@ -10,6 +11,7 @@ import {
OGDialog,
Accordion,
TrashIcon,
TooltipAnchor,
InfoHoverCard,
AccordionItem,
OGDialogTrigger,
@ -25,13 +27,125 @@ import { cn } from '~/utils';
export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo }) {
const localize = useLocalize();
const { removeTool } = useRemoveMCPTool();
const { getValues, setValue } = useFormContext<AgentForm>();
const { getValues, setValue, control } = useFormContext<AgentForm>();
const { getServerStatusIconProps, getConfigDialogProps } = useMCPServerManager();
const [isFocused, setIsFocused] = useState(false);
const [isHovering, setIsHovering] = useState(false);
const [accordionValue, setAccordionValue] = useState<string>('');
/** Local state for optimistic updates */
const [localDeferredTools, setLocalDeferredTools] = useState<Set<string>>(new Set());
/** Watch form tool_options for sync */
const formToolOptions = useWatch({ control, name: 'tool_options' });
/** Sync local state with form state */
useEffect(() => {
const newDeferred = new Set<string>();
if (formToolOptions) {
for (const [toolId, options] of Object.entries(formToolOptions)) {
if (options?.defer_loading) {
newDeferred.add(toolId);
}
}
}
setLocalDeferredTools(newDeferred);
}, [formToolOptions]);
/** Check if a specific tool has defer_loading enabled (uses local state for optimistic UI) */
const isToolDeferred = useCallback(
(toolId: string): boolean => localDeferredTools.has(toolId),
[localDeferredTools],
);
/** Toggle defer_loading for a specific tool with optimistic update */
const toggleToolDefer = useCallback(
(toolId: string) => {
const newDeferred = !localDeferredTools.has(toolId);
/** Optimistic update */
setLocalDeferredTools((prev) => {
const next = new Set(prev);
if (newDeferred) {
next.add(toolId);
} else {
next.delete(toolId);
}
return next;
});
/** Update form state */
const currentOptions = getValues('tool_options') || {};
const currentToolOptions = currentOptions[toolId] || {};
const updatedOptions: AgentToolOptions = {
...currentOptions,
[toolId]: {
...currentToolOptions,
defer_loading: newDeferred,
},
};
/** Clean up if no options remain for this tool */
if (!newDeferred && Object.keys(updatedOptions[toolId]).length === 1) {
delete updatedOptions[toolId];
}
setValue('tool_options', updatedOptions, { shouldDirty: true });
},
[localDeferredTools, getValues, setValue],
);
/** Check if all server tools are deferred (uses local state) */
const areAllToolsDeferred =
serverInfo?.tools &&
serverInfo.tools.length > 0 &&
serverInfo.tools.every((tool) => localDeferredTools.has(tool.tool_id));
/** Toggle defer_loading for all tools from this server with optimistic update */
const toggleDeferAll = useCallback(() => {
if (!serverInfo?.tools) return;
const shouldDefer = !areAllToolsDeferred;
/** Optimistic update */
setLocalDeferredTools((prev) => {
const next = new Set(prev);
for (const tool of serverInfo.tools!) {
if (shouldDefer) {
next.add(tool.tool_id);
} else {
next.delete(tool.tool_id);
}
}
return next;
});
/** Update form state */
const currentOptions = getValues('tool_options') || {};
const updatedOptions: AgentToolOptions = { ...currentOptions };
for (const tool of serverInfo.tools) {
if (shouldDefer) {
updatedOptions[tool.tool_id] = {
...(updatedOptions[tool.tool_id] || {}),
defer_loading: true,
};
} else {
if (updatedOptions[tool.tool_id]) {
delete updatedOptions[tool.tool_id].defer_loading;
/** Clean up empty tool options */
if (Object.keys(updatedOptions[tool.tool_id]).length === 0) {
delete updatedOptions[tool.tool_id];
}
}
}
}
setValue('tool_options', updatedOptions, { shouldDirty: true });
}, [serverInfo?.tools, getValues, setValue, areAllToolsDeferred]);
if (!serverInfo) {
return null;
}
@ -170,6 +284,47 @@ export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo })
/>
</div>
{/* Defer All toggle - icon only with tooltip */}
<TooltipAnchor
description={
areAllToolsDeferred
? localize('com_ui_mcp_undefer_all')
: localize('com_ui_mcp_defer_all')
}
side="top"
role="button"
tabIndex={isExpanded ? 0 : -1}
aria-label={
areAllToolsDeferred
? localize('com_ui_mcp_undefer_all')
: localize('com_ui_mcp_defer_all')
}
aria-pressed={areAllToolsDeferred}
className={cn(
'flex h-7 w-7 items-center justify-center rounded transition-colors duration-200',
'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-1',
isExpanded ? 'visible' : 'pointer-events-none invisible',
areAllToolsDeferred
? 'bg-amber-500/20 text-amber-500 hover:bg-amber-500/30'
: 'text-text-tertiary hover:bg-surface-hover hover:text-text-primary',
)}
onClick={(e) => {
e.stopPropagation();
toggleDeferAll();
}}
onKeyDown={(e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
e.stopPropagation();
toggleDeferAll();
}
}}
>
<Clock
className={cn('h-4 w-4', areAllToolsDeferred && 'fill-amber-500/30')}
/>
</TooltipAnchor>
<div className="flex items-center gap-1">
{/* Caret button for accordion */}
<AccordionPrimitive.Trigger asChild>
@ -230,52 +385,95 @@ export default function MCPTool({ serverInfo }: { serverInfo?: MCPServerInfo })
<AccordionContent className="relative ml-1 pt-1 before:absolute before:bottom-2 before:left-0 before:top-0 before:w-0.5 before:bg-border-medium">
<div className="space-y-1">
{serverInfo.tools?.map((subTool) => (
<label
key={subTool.tool_id}
htmlFor={subTool.tool_id}
className={cn(
'group/item border-token-border-light hover:bg-token-surface-secondary flex cursor-pointer items-center rounded-lg border p-2',
'ml-2 mr-1 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background',
)}
onClick={(e) => e.stopPropagation()}
onKeyDown={(e) => {
e.stopPropagation();
}}
>
<Checkbox
id={subTool.tool_id}
checked={selectedTools.includes(subTool.tool_id)}
onCheckedChange={(_checked) => {
const newSelectedTools = selectedTools.includes(subTool.tool_id)
? selectedTools.filter((t) => t !== subTool.tool_id)
: [...selectedTools, subTool.tool_id];
updateFormTools(newSelectedTools);
}}
{serverInfo.tools?.map((subTool) => {
const isDeferred = isToolDeferred(subTool.tool_id);
return (
<label
key={subTool.tool_id}
htmlFor={subTool.tool_id}
className={cn(
'group/item flex cursor-pointer items-center rounded-lg border p-2',
'ml-2 mr-1 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background',
isDeferred
? 'border-amber-500/50 bg-amber-500/5 hover:bg-amber-500/10'
: 'border-token-border-light hover:bg-token-surface-secondary',
)}
onClick={(e) => e.stopPropagation()}
onKeyDown={(e) => {
e.stopPropagation();
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
const checkbox = e.currentTarget as HTMLButtonElement;
checkbox.click();
}
}}
onClick={(e) => e.stopPropagation()}
className={cn(
'relative float-left mr-2 inline-flex h-4 w-4 cursor-pointer rounded border border-border-medium transition-[border-color] duration-200 hover:border-border-heavy focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background',
)}
aria-label={subTool.metadata.name}
/>
<span className="text-token-text-primary select-none">
{subTool.metadata.name}
</span>
{subTool.metadata.description && (
<div className="ml-auto flex items-center opacity-0 transition-opacity duration-200 group-focus-within/item:opacity-100 group-hover/item:opacity-100">
<InfoHoverCard side={ESide.Left} text={subTool.metadata.description} />
>
<Checkbox
id={subTool.tool_id}
checked={selectedTools.includes(subTool.tool_id)}
onCheckedChange={(_checked) => {
const newSelectedTools = selectedTools.includes(subTool.tool_id)
? selectedTools.filter((t) => t !== subTool.tool_id)
: [...selectedTools, subTool.tool_id];
updateFormTools(newSelectedTools);
}}
onKeyDown={(e) => {
e.stopPropagation();
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
const checkbox = e.currentTarget as HTMLButtonElement;
checkbox.click();
}
}}
onClick={(e) => e.stopPropagation()}
className={cn(
'relative float-left mr-2 inline-flex h-4 w-4 cursor-pointer rounded border border-border-medium transition-[border-color] duration-200 hover:border-border-heavy focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background',
)}
aria-label={subTool.metadata.name}
/>
<span className="text-token-text-primary flex-1 select-none">
{subTool.metadata.name}
</span>
<div className="ml-auto flex items-center gap-1">
{/* Per-tool defer toggle - icon only */}
<TooltipAnchor
description={
isDeferred
? localize('com_ui_mcp_click_to_undefer')
: localize('com_ui_mcp_click_to_defer')
}
side="top"
role="button"
aria-label={
isDeferred
? localize('com_ui_mcp_undefer')
: localize('com_ui_mcp_defer_loading')
}
aria-pressed={isDeferred}
className={cn(
'flex h-6 w-6 items-center justify-center rounded transition-all duration-200',
'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-1',
isDeferred
? 'bg-amber-500/20 text-amber-500 hover:bg-amber-500/30'
: 'text-text-tertiary opacity-0 hover:bg-surface-hover hover:text-text-primary group-focus-within/item:opacity-100 group-hover/item:opacity-100',
)}
onClick={(e) => {
e.stopPropagation();
e.preventDefault();
toggleToolDefer(subTool.tool_id);
}}
onKeyDown={(e) => {
e.stopPropagation();
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
toggleToolDefer(subTool.tool_id);
}
}}
>
<Clock className={cn('h-3.5 w-3.5', isDeferred && 'fill-amber-500/30')} />
</TooltipAnchor>
{subTool.metadata.description && (
<InfoHoverCard side={ESide.Left} text={subTool.metadata.description} />
)}
</div>
)}
</label>
))}
</label>
);
})}
</div>
</AccordionContent>
</AccordionItem>

10
client/src/locales/en/translation.json
View file

@ -1095,6 +1095,16 @@
"com_ui_mcp_type_streamable_http": "Streamable HTTPS",
"com_ui_mcp_update_var": "Update {{0}}",
"com_ui_mcp_url": "MCP Server URL",
"com_ui_mcp_defer_loading": "Defer loading",
"com_ui_mcp_defer": "Defer",
"com_ui_mcp_defer_all": "Defer all tools",
"com_ui_mcp_deferred": "Deferred",
"com_ui_mcp_undefer": "Undefer",
"com_ui_mcp_undefer_all": "Undefer all tools",
"com_ui_mcp_click_to_defer": "Click to defer - tool will be discoverable via search but not loaded until needed",
"com_ui_mcp_click_to_undefer": "Click to undefer - tool will be loaded immediately",
"com_ui_mcp_defer_loading_description": "Tool is discoverable via search but not loaded until needed. Saves context window tokens.",
"com_ui_mcp_defer_all_description": "Defer all tools from this server for discovery via tool search",
"com_ui_medium": "Medium",
"com_ui_memories": "Memories",
"com_ui_memories_allow_create": "Allow creating Memories",

86
packages/api/src/tools/classification.ts
View file

@ -27,6 +27,7 @@
import { logger } from '@librechat/data-schemas';
import { Constants } from 'librechat-data-provider';
import { EnvVar, createProgrammaticToolCallingTool, createToolSearch } from '@librechat/agents';
import type { AgentToolOptions } from 'librechat-data-provider';
import type {
LCToolRegistry,
JsonSchemaType,
@ -180,6 +181,64 @@ export function buildToolRegistryFromEnv(tools: ToolDefinition[]): LCToolRegistr
return registry;
}
/**
* Builds a tool registry from agent-level tool_options.
* This takes precedence over environment variable configuration when provided.
*
* @param tools - Array of tool definitions
* @param agentToolOptions - Per-tool configuration from the agent
* @returns Map of tool name to tool definition with classification
*/
export function buildToolRegistryFromAgentOptions(
tools: ToolDefinition[],
agentToolOptions: AgentToolOptions,
): LCToolRegistry {
/** Fall back to env vars for tools not configured at agent level */
const programmaticOnly = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY);
const programmaticOnlyExclude = parseToolList(process.env.TOOL_PROGRAMMATIC_ONLY_EXCLUDE);
const dualContext = parseToolList(process.env.TOOL_DUAL_CONTEXT);
const dualContextExclude = parseToolList(process.env.TOOL_DUAL_CONTEXT_EXCLUDE);
const registry: LCToolRegistry = new Map();
for (const tool of tools) {
const { name, description, parameters } = tool;
const agentOptions = agentToolOptions[name];
/** Determine allowed_callers: agent options take precedence, then env vars, then default */
let allowed_callers: AllowedCaller[];
if (agentOptions?.allowed_callers && agentOptions.allowed_callers.length > 0) {
allowed_callers = agentOptions.allowed_callers;
} else if (toolMatchesPatterns(name, programmaticOnly, programmaticOnlyExclude)) {
allowed_callers = ['code_execution'];
} else if (toolMatchesPatterns(name, dualContext, dualContextExclude)) {
allowed_callers = ['direct', 'code_execution'];
} else {
allowed_callers = ['direct'];
}
/** Determine defer_loading: agent options take precedence (explicit true/false) */
const defer_loading = agentOptions?.defer_loading === true;
const toolDef: LCTool = {
name,
allowed_callers,
defer_loading,
};
if (description) {
toolDef.description = description;
}
if (parameters) {
toolDef.parameters = parameters;
}
registry.set(name, toolDef);
}
return registry;
}
/**
* Checks if PTC (Programmatic Tool Calling) should be enabled based on environment configuration.
* PTC is enabled if any tools or server patterns are configured for programmatic calling.
@ -261,6 +320,8 @@ export interface BuildToolClassificationParams {
userId: string;
/** Agent ID (used to check if this agent should have classification features) */
agentId?: string;
/** Per-tool configuration from the agent (takes precedence over env vars) */
agentToolOptions?: AgentToolOptions;
/** Function to load auth values (dependency injection) */
loadAuthValues: (params: {
userId: string;
@ -328,18 +389,20 @@ export function agentHasDeferredTools(toolRegistry: LCToolRegistry): boolean {
* This function:
* 1. Checks if the agent is allowed for classification features (via TOOL_CLASSIFICATION_AGENT_IDS)
* 2. Filters loaded tools for MCP tools
* 3. Extracts tool definitions and builds the registry from env vars
* 3. Extracts tool definitions and builds the registry
* - Uses agent's tool_options if provided (UI-based configuration)
* - Falls back to env vars for tools not configured at agent level
* 4. Cleans up temporary mcpJsonSchema properties
* 5. Creates PTC tool only if agent has tools configured for programmatic calling
* 6. Creates tool search tool only if agent has deferred tools
*
* @param params - Parameters including loaded tools, userId, agentId, and dependencies
* @param params - Parameters including loaded tools, userId, agentId, agentToolOptions, and dependencies
* @returns Tool registry and any additional tools created
*/
export async function buildToolClassification(
params: BuildToolClassificationParams,
): Promise<BuildToolClassificationResult> {
const { loadedTools, userId, agentId, loadAuthValues } = params;
const { loadedTools, userId, agentId, agentToolOptions, loadAuthValues } = params;
const additionalTools: GenericTool[] = [];
/** Check if this agent is allowed to have classification features (requires agentId) */
@ -356,7 +419,22 @@ export async function buildToolClassification(
}
const mcpToolDefs = mcpTools.map(extractMCPToolDefinition);
const toolRegistry = buildToolRegistryFromEnv(mcpToolDefs);
/**
* Build registry from agent's tool_options if provided (UI config).
* Environment variable-based classification is only used as fallback
* when TOOL_CLASSIFICATION_FROM_ENV=true is explicitly set.
*/
let toolRegistry: LCToolRegistry | undefined;
if (agentToolOptions && Object.keys(agentToolOptions).length > 0) {
toolRegistry = buildToolRegistryFromAgentOptions(mcpToolDefs, agentToolOptions);
} else if (process.env.TOOL_CLASSIFICATION_FROM_ENV === 'true') {
toolRegistry = buildToolRegistryFromEnv(mcpToolDefs);
} else {
/** No agent-level config and env-based classification not enabled */
return { toolRegistry: undefined, additionalTools };
}
/** Clean up temporary mcpJsonSchema property from tools now that registry is populated */
cleanupMCPToolSchemas(mcpTools);

1
packages/data-provider/src/schemas.ts
View file

@ -224,6 +224,7 @@ export const defaultAgentFormValues = {
model: '',
model_parameters: {},
tools: [],
tool_options: {},
provider: {},
projectIds: [],
edges: [],

36
packages/data-provider/src/types/assistants.ts
View file

@ -206,6 +206,38 @@ export type SupportContact = {
email?: string;
};
/**
* Specifies who can invoke a tool.
* - 'direct': LLM can call directly
* - 'code_execution': Only callable via programmatic tool calling (PTC)
*/
export type AllowedCaller = 'direct' | 'code_execution';
/**
* Per-tool configuration options stored at the agent level.
* Keyed by tool_id (e.g., "search_mcp_github").
*/
export type ToolOptions = {
/**
* If true, the tool uses deferred loading (discoverable via tool search).
* @default false
*/
defer_loading?: boolean;
/**
* Specifies who can invoke this tool.
* - 'direct': LLM can call directly (default behavior)
* - 'code_execution': Only callable via PTC sandbox
* @default ['direct']
*/
allowed_callers?: AllowedCaller[];
};
/**
* Map of tool_id to its configuration options.
* Used to customize tool behavior per agent.
*/
export type AgentToolOptions = Record<string, ToolOptions>;
export type Agent = {
_id?: string;
id: string;
@ -241,6 +273,8 @@ export type Agent = {
version?: number;
category?: string;
support_contact?: SupportContact;
/** Per-tool configuration options (deferred loading, allowed callers, etc.) */
tool_options?: AgentToolOptions;
};
export type TAgentsMap = Record<string, Agent | undefined>;
@ -265,6 +299,7 @@ export type AgentCreateParams = {
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
>;
export type AgentUpdateParams = {
@ -291,6 +326,7 @@ export type AgentUpdateParams = {
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
>;
export type AgentListParams = {