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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧑🏫 fix: Multi-Agent Instructions Handling (#11484)
Danny Avilacfd5c793a9ee
diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 5f3618de4c..35cf7de784 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -1,6 +1,5 @@require('events').EventEmitter.defaultMaxListeners = 100;const { logger } = require('@librechat/data-schemas');-const { DynamicStructuredTool } = require('@langchain/core/tools');const { getBufferString, HumanMessage } = require('@langchain/core/messages');const {createRun,@@ -14,6 +13,7 @@ const {getBalanceConfig,getProviderConfig,memoryInstructions,+ applyContextToAgent,GenerationJobManager,getTransactionsConfig,createMemoryProcessor,@@ -328,11 +328,13 @@ class AgentClient extends BaseClient {);}+ /**+ * Returns build message options. For AgentClient, agent-specific instructions+ * are retrieved directly from agent objects in buildMessages, so this returns empty.+ * @returns {Object} Empty options object+ */getBuildMessagesOptions() {- return {- instructions: this.options.agent.instructions,- additional_instructions: this.options.agent.additional_instructions,- };+ return {};}/**@@ -355,12 +357,7 @@ class AgentClient extends BaseClient {return files;}- async buildMessages(- messages,- parentMessageId,- { instructions = null, additional_instructions = null },- opts,- ) {+ async buildMessages(messages, parentMessageId, _buildOptions, opts) {/** Always pass mapMethod; getMessagesForConversation applies it only to messages with addedConvo flag */const orderedMessages = this.constructor.getMessagesForConversation({messages,@@ -374,11 +371,29 @@ class AgentClient extends BaseClient {/** @type {number | undefined} */let promptTokens;- /** @type {string} */- let systemContent = [instructions ?? '', additional_instructions ?? '']- .filter(Boolean)- .join('\n')- .trim();+ /**+ * Extract base instructions for all agents (combines instructions + additional_instructions).+ * This must be done before applying context to preserve the original agent configuration.+ */+ const extractBaseInstructions = (agent) => {+ const baseInstructions = [agent.instructions ?? '', agent.additional_instructions ?? '']+ .filter(Boolean)+ .join('\n')+ .trim();+ agent.instructions = baseInstructions;+ return agent;+ };++ /** Collect all agents for unified processing, extracting base instructions during collection */+ const allAgents = [+ { agent: extractBaseInstructions(this.options.agent), agentId: this.options.agent.id },+ ...(this.agentConfigs?.size > 0+ ? Array.from(this.agentConfigs.entries()).map(([agentId, agent]) => ({+ agent: extractBaseInstructions(agent),+ agentId,+ }))+ : []),+ ];if (this.options.attachments) {const attachments = await this.options.attachments;@@ -413,6 +428,7 @@ class AgentClient extends BaseClient {assistantName: this.options?.modelLabel,});+ /** For non-latest messages, prepend file context directly to message content */if (message.fileContext && i !== orderedMessages.length - 1) {if (typeof formattedMessage.content === 'string') {formattedMessage.content = message.fileContext + '\n' + formattedMessage.content;@@ -422,8 +438,6 @@ class AgentClient extends BaseClient {? (textPart.text = message.fileContext + '\n' + textPart.text): formattedMessage.content.unshift({ type: 'text', text: message.fileContext });}- } else if (message.fileContext && i === orderedMessages.length - 1) {- systemContent = [systemContent, message.fileContext].join('\n');}const needsTokenCount =@@ -456,46 +470,35 @@ class AgentClient extends BaseClient {return formattedMessage;});- if (this.contextHandlers) {- this.augmentedPrompt = await this.contextHandlers.createContext();- systemContent = this.augmentedPrompt + systemContent;- }-- // Inject MCP server instructions if available- const ephemeralAgent = this.options.req.body.ephemeralAgent;- let mcpServers = [];+ /**+ * Build shared run context - applies to ALL agents in the run.+ * This includes: file context (latest message), augmented prompt (RAG), memory context.+ */+ const sharedRunContextParts = [];- // Check for ephemeral agent MCP servers- if (ephemeralAgent && ephemeralAgent.mcp && ephemeralAgent.mcp.length > 0) {- mcpServers = ephemeralAgent.mcp;- }- // Check for regular agent MCP tools- else if (this.options.agent && this.options.agent.tools) {- mcpServers = this.options.agent.tools- .filter(- (tool) =>- tool instanceof DynamicStructuredTool && tool.name.includes(Constants.mcp_delimiter),- )- .map((tool) => tool.name.split(Constants.mcp_delimiter).pop())- .filter(Boolean);+ /** File context from the latest message (attachments) */+ const latestMessage = orderedMessages[orderedMessages.length - 1];+ if (latestMessage?.fileContext) {+ sharedRunContextParts.push(latestMessage.fileContext);}- if (mcpServers.length > 0) {- try {- const mcpInstructions = await getMCPManager().formatInstructionsForContext(mcpServers);- if (mcpInstructions) {- systemContent = [systemContent, mcpInstructions].filter(Boolean).join('\n\n');- logger.debug('[AgentClient] Injected MCP instructions for servers:', mcpServers);- }- } catch (error) {- logger.error('[AgentClient] Failed to inject MCP instructions:', error);+ /** Augmented prompt from RAG/context handlers */+ if (this.contextHandlers) {+ this.augmentedPrompt = await this.contextHandlers.createContext();+ if (this.augmentedPrompt) {+ sharedRunContextParts.push(this.augmentedPrompt);}}- if (systemContent) {- this.options.agent.instructions = systemContent;+ /** Memory context (user preferences/memories) */+ const withoutKeys = await this.useMemory();+ if (withoutKeys) {+ const memoryContext = `${memoryInstructions}\n\n# Existing memory about the user:\n${withoutKeys}`;+ sharedRunContextParts.push(memoryContext);}+ const sharedRunContext = sharedRunContextParts.join('\n\n');+/** @type {Record<string, number> | undefined} */let tokenCountMap;@@ -521,36 +524,27 @@ class AgentClient extends BaseClient {opts.getReqData({ promptTokens });}- const withoutKeys = await this.useMemory();- const memoryContext = withoutKeys- ? `${memoryInstructions}\n\n# Existing memory about the user:\n${withoutKeys}`- : '';- if (memoryContext) {- systemContent += memoryContext;- }-- if (systemContent) {- this.options.agent.instructions = systemContent;- }-/**- * Pass memory context to parallel agents (addedConvo) so they have the same user context.+ * Apply context to all agents.+ * Each agent gets: shared run context + their own base instructions + their own MCP instructions.*- * NOTE: This intentionally mutates the agentConfig objects in place. The agentConfigs Map- * holds references to config objects that will be passed to the graph runtime. Mutating- * them here ensures all parallel agents receive the memory context before execution starts.- * Creating new objects would not work because the Map references would still point to the old objects.+ * NOTE: This intentionally mutates agent objects in place. The agentConfigs Map+ * holds references to config objects that will be passed to the graph runtime.*/- if (memoryContext && this.agentConfigs?.size > 0) {- for (const [agentId, agentConfig] of this.agentConfigs.entries()) {- if (agentConfig.instructions) {- agentConfig.instructions = agentConfig.instructions + '\n\n' + memoryContext;- } else {- agentConfig.instructions = memoryContext;- }- logger.debug(`[AgentClient] Added memory context to parallel agent: ${agentId}`);- }- }+ const ephemeralAgent = this.options.req.body.ephemeralAgent;+ const mcpManager = getMCPManager();+ await Promise.all(+ allAgents.map(({ agent, agentId }) =>+ applyContextToAgent({+ agent,+ agentId,+ logger,+ mcpManager,+ sharedRunContext,+ ephemeralAgent: agentId === this.options.agent.id ? ephemeralAgent : undefined,+ }),+ ),+ );return result;}diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.jsindex 402d011fd6..b5899c5215 100644--- a/api/server/controllers/agents/client.test.js+++ b/api/server/controllers/agents/client.test.js@@ -1310,8 +1310,8 @@ describe('AgentClient - titleConvo', () => {expect(client.options.agent.instructions).toContain('# MCP Server Instructions');expect(client.options.agent.instructions).toContain('Use these tools carefully');- // Verify the base instructions are also included- expect(client.options.agent.instructions).toContain('Base instructions');+ // Verify the base instructions are also included (from agent config, not buildOptions)+ expect(client.options.agent.instructions).toContain('Base agent instructions');});it('should handle MCP instructions with ephemeral agent', async () => {@@ -1373,8 +1373,8 @@ describe('AgentClient - titleConvo', () => {additional_instructions: null,});- // Verify the instructions still work without MCP content- expect(client.options.agent.instructions).toBe('Base instructions only');+ // Verify the instructions still work without MCP content (from agent config, not buildOptions)+ expect(client.options.agent.instructions).toBe('Base agent instructions');expect(client.options.agent.instructions).not.toContain('[object Promise]');});@@ -1398,8 +1398,8 @@ describe('AgentClient - titleConvo', () => {additional_instructions: null,});- // Should still have base instructions without MCP content- expect(client.options.agent.instructions).toContain('Base instructions');+ // Should still have base instructions without MCP content (from agent config, not buildOptions)+ expect(client.options.agent.instructions).toContain('Base agent instructions');expect(client.options.agent.instructions).not.toContain('[object Promise]');});});@@ -1945,7 +1945,8 @@ describe('AgentClient - titleConvo', () => {expect(client.useMemory).toHaveBeenCalled();- expect(client.options.agent.instructions).toContain('Base instructions');+ // Verify primary agent has its configured instructions (not from buildOptions) and memory context+ expect(client.options.agent.instructions).toContain('Primary agent instructions');expect(client.options.agent.instructions).toContain(memoryContent);expect(parallelAgent1.instructions).toContain('Parallel agent 1 instructions');diff --git a/packages/api/src/agents/context.spec.ts b/packages/api/src/agents/context.spec.tsnew file mode 100644index 0000000000..c5358209c7--- /dev/null+++ b/packages/api/src/agents/context.spec.ts@@ -0,0 +1,528 @@+import { z } from 'zod';+import { Constants } from 'librechat-data-provider';+import { DynamicStructuredTool } from '@langchain/core/tools';+import type { Logger } from 'winston';+import type { MCPManager } from '~/mcp/MCPManager';+import {+ extractMCPServers,+ getMCPInstructionsForServers,+ buildAgentInstructions,+ applyContextToAgent,+} from './context';++// Test schema for DynamicStructuredTool+const testSchema = z.object({});++describe('Agent Context Utilities', () => {+ describe('extractMCPServers', () => {+ it('should return empty array when agent has no tools', () => {+ const agent = { id: 'test-agent' };+ expect(extractMCPServers(agent)).toEqual([]);+ });++ it('should return empty array when agent tools array is empty', () => {+ const agent = { id: 'test-agent', tools: [] };+ expect(extractMCPServers(agent)).toEqual([]);+ });++ it('should extract unique MCP server names from tools', () => {+ const tool1 = new DynamicStructuredTool({+ name: `tool1${Constants.mcp_delimiter}server1`,+ description: 'Test tool 1',+ schema: testSchema,+ func: async () => 'result',+ });++ const tool2 = new DynamicStructuredTool({+ name: `tool2${Constants.mcp_delimiter}server2`,+ description: 'Test tool 2',+ schema: testSchema,+ func: async () => 'result',+ });++ const agent = { id: 'test-agent', tools: [tool1, tool2] };+ const result = extractMCPServers(agent);++ expect(result).toContain('server1');+ expect(result).toContain('server2');+ expect(result).toHaveLength(2);+ });++ it('should return unique server names when multiple tools use same server', () => {+ const tool1 = new DynamicStructuredTool({+ name: `tool1${Constants.mcp_delimiter}server1`,+ description: 'Test tool 1',+ schema: testSchema,+ func: async () => 'result',+ });++ const tool2 = new DynamicStructuredTool({+ name: `tool2${Constants.mcp_delimiter}server1`,+ description: 'Test tool 2',+ schema: testSchema,+ func: async () => 'result',+ });++ const agent = { id: 'test-agent', tools: [tool1, tool2] };+ const result = extractMCPServers(agent);++ expect(result).toEqual(['server1']);+ expect(result).toHaveLength(1);+ });++ it('should ignore tools without MCP delimiter', () => {+ const mcpTool = new DynamicStructuredTool({+ name: `tool1${Constants.mcp_delimiter}server1`,+ description: 'MCP tool',+ schema: testSchema,+ func: async () => 'result',+ });++ const regularTool = new DynamicStructuredTool({+ name: 'regular_tool',+ description: 'Regular tool',+ schema: testSchema,+ func: async () => 'result',+ });++ const agent = { id: 'test-agent', tools: [mcpTool, regularTool] };+ const result = extractMCPServers(agent);++ expect(result).toEqual(['server1']);+ expect(result).toHaveLength(1);+ });++ it('should handle mixed tool types (string and DynamicStructuredTool)', () => {+ const mcpTool = new DynamicStructuredTool({+ name: `tool1${Constants.mcp_delimiter}server1`,+ description: 'MCP tool',+ schema: testSchema,+ func: async () => 'result',+ });++ const agent = { id: 'test-agent', tools: [mcpTool, 'string-tool'] };+ const result = extractMCPServers(agent);++ expect(result).toEqual(['server1']);+ });++ it('should filter out empty server names', () => {+ const toolWithEmptyServer = new DynamicStructuredTool({+ name: `tool1${Constants.mcp_delimiter}`,+ description: 'Tool with empty server',+ schema: testSchema,+ func: async () => 'result',+ });++ const agent = { id: 'test-agent', tools: [toolWithEmptyServer] };+ const result = extractMCPServers(agent);++ expect(result).toEqual([]);+ });+ });++ describe('getMCPInstructionsForServers', () => {+ let mockMCPManager: jest.Mocked<MCPManager>;+ let mockLogger: Logger;++ beforeEach(() => {+ mockMCPManager = {+ formatInstructionsForContext: jest.fn(),+ } as unknown as jest.Mocked<MCPManager>;++ mockLogger = {+ debug: jest.fn(),+ error: jest.fn(),+ } as unknown as Logger;+ });++ it('should return empty string when server array is empty', async () => {+ const result = await getMCPInstructionsForServers([], mockMCPManager, mockLogger);++ expect(result).toBe('');+ expect(mockMCPManager.formatInstructionsForContext).not.toHaveBeenCalled();+ });++ it('should fetch and return MCP instructions successfully', async () => {+ const instructions = '# MCP Instructions\nUse these tools carefully';+ mockMCPManager.formatInstructionsForContext.mockResolvedValue(instructions);++ const result = await getMCPInstructionsForServers(+ ['server1', 'server2'],+ mockMCPManager,+ mockLogger,+ );++ expect(result).toBe(instructions);+ expect(mockMCPManager.formatInstructionsForContext).toHaveBeenCalledWith([+ 'server1',+ 'server2',+ ]);+ expect(mockLogger.debug).toHaveBeenCalledWith(+ '[AgentContext] Fetched MCP instructions for servers:',+ ['server1', 'server2'],+ );+ });++ it('should return empty string when MCP manager returns empty', async () => {+ mockMCPManager.formatInstructionsForContext.mockResolvedValue('');++ const result = await getMCPInstructionsForServers(['server1'], mockMCPManager, mockLogger);++ expect(result).toBe('');+ expect(mockLogger.debug).not.toHaveBeenCalled();+ });++ it('should handle errors gracefully and log them', async () => {+ const error = new Error('MCP fetch failed');+ mockMCPManager.formatInstructionsForContext.mockRejectedValue(error);++ const result = await getMCPInstructionsForServers(['server1'], mockMCPManager, mockLogger);++ expect(result).toBe('');+ expect(mockLogger.error).toHaveBeenCalledWith(+ '[AgentContext] Failed to get MCP instructions:',+ error,+ );+ });++ it('should work without logger', async () => {+ const instructions = 'Test instructions';+ mockMCPManager.formatInstructionsForContext.mockResolvedValue(instructions);++ const result = await getMCPInstructionsForServers(['server1'], mockMCPManager);++ expect(result).toBe(instructions);+ // Should not throw even without logger+ });++ it('should handle errors without logger', async () => {+ mockMCPManager.formatInstructionsForContext.mockRejectedValue(new Error('Test error'));++ const result = await getMCPInstructionsForServers(['server1'], mockMCPManager);++ expect(result).toBe('');+ // Should not throw even without logger+ });+ });++ describe('buildAgentInstructions', () => {+ it('should combine all parts with double newlines', () => {+ const result = buildAgentInstructions({+ sharedRunContext: 'Shared context',+ baseInstructions: 'Base instructions',+ mcpInstructions: 'MCP instructions',+ });++ expect(result).toBe('Shared context\n\nBase instructions\n\nMCP instructions');+ });++ it('should filter out empty parts', () => {+ const result = buildAgentInstructions({+ sharedRunContext: 'Shared context',+ baseInstructions: '',+ mcpInstructions: 'MCP instructions',+ });++ expect(result).toBe('Shared context\n\nMCP instructions');+ });++ it('should return undefined when all parts are empty', () => {+ const result = buildAgentInstructions({+ sharedRunContext: '',+ baseInstructions: '',+ mcpInstructions: '',+ });++ expect(result).toBeUndefined();+ });++ it('should handle only shared context', () => {+ const result = buildAgentInstructions({+ sharedRunContext: 'Shared context only',+ });++ expect(result).toBe('Shared context only');+ });++ it('should handle only base instructions', () => {+ const result = buildAgentInstructions({+ baseInstructions: 'Base instructions only',+ });++ expect(result).toBe('Base instructions only');+ });++ it('should handle only MCP instructions', () => {+ const result = buildAgentInstructions({+ mcpInstructions: 'MCP instructions only',+ });++ expect(result).toBe('MCP instructions only');+ });++ it('should trim whitespace from combined result', () => {+ const result = buildAgentInstructions({+ sharedRunContext: ' Shared context ',+ baseInstructions: ' Base instructions ',+ });++ expect(result).toBe('Shared context \n\n Base instructions');+ });++ it('should handle undefined parts', () => {+ const result = buildAgentInstructions({+ sharedRunContext: undefined,+ baseInstructions: 'Base',+ mcpInstructions: undefined,+ });++ expect(result).toBe('Base');+ });+ });++ describe('applyContextToAgent', () => {+ let mockMCPManager: jest.Mocked<MCPManager>;+ let mockLogger: Logger;++ beforeEach(() => {+ mockMCPManager = {+ formatInstructionsForContext: jest.fn(),+ } as unknown as jest.Mocked<MCPManager>;++ mockLogger = {+ debug: jest.fn(),+ error: jest.fn(),+ } as unknown as Logger;+ });++ it('should apply context successfully with all components', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Original instructions',+ tools: [+ new DynamicStructuredTool({+ name: `tool${Constants.mcp_delimiter}server1`,+ description: 'Test tool',+ schema: testSchema,+ func: async () => 'result',+ }),+ ],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('MCP instructions');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Shared context',+ mcpManager: mockMCPManager,+ agentId: 'test-agent',+ logger: mockLogger,+ });++ expect(agent.instructions).toBe(+ 'Shared context\n\nOriginal instructions\n\nMCP instructions',+ );+ expect(mockLogger.debug).toHaveBeenCalledWith(+ '[AgentContext] Applied context to agent: test-agent',+ );+ });++ it('should use ephemeral agent MCP servers when provided', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base instructions',+ tools: [],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('Ephemeral MCP');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Context',+ mcpManager: mockMCPManager,+ ephemeralAgent: { mcp: ['ephemeral-server'] },+ logger: mockLogger,+ });++ expect(mockMCPManager.formatInstructionsForContext).toHaveBeenCalledWith([+ 'ephemeral-server',+ ]);+ expect(agent.instructions).toContain('Ephemeral MCP');+ });++ it('should prefer agent tools over empty ephemeral MCP array', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base',+ tools: [+ new DynamicStructuredTool({+ name: `tool${Constants.mcp_delimiter}agent-server`,+ description: 'Test tool',+ schema: testSchema,+ func: async () => 'result',+ }),+ ],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('Agent MCP');++ await applyContextToAgent({+ agent,+ sharedRunContext: '',+ mcpManager: mockMCPManager,+ ephemeralAgent: { mcp: [] },+ logger: mockLogger,+ });++ expect(mockMCPManager.formatInstructionsForContext).toHaveBeenCalledWith(['agent-server']);+ });++ it('should work without agentId', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base',+ tools: [],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Context',+ mcpManager: mockMCPManager,+ logger: mockLogger,+ });++ expect(agent.instructions).toBe('Context\n\nBase');+ expect(mockLogger.debug).not.toHaveBeenCalled();+ });++ it('should work without logger', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base',+ tools: [+ new DynamicStructuredTool({+ name: `tool${Constants.mcp_delimiter}server1`,+ description: 'Test tool',+ schema: testSchema,+ func: async () => 'result',+ }),+ ],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('MCP');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Context',+ mcpManager: mockMCPManager,+ });++ expect(agent.instructions).toBe('Context\n\nBase\n\nMCP');+ });++ it('should handle MCP fetch error gracefully and set fallback instructions', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base instructions',+ tools: [+ new DynamicStructuredTool({+ name: `tool${Constants.mcp_delimiter}server1`,+ description: 'Test tool',+ schema: testSchema,+ func: async () => 'result',+ }),+ ],+ };++ const error = new Error('MCP fetch failed');+ mockMCPManager.formatInstructionsForContext.mockRejectedValue(error);++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Shared context',+ mcpManager: mockMCPManager,+ agentId: 'test-agent',+ logger: mockLogger,+ });++ // getMCPInstructionsForServers catches the error and returns empty string+ // So agent still has shared context + base instructions (without MCP)+ expect(agent.instructions).toBe('Shared context\n\nBase instructions');+ // Error is logged by getMCPInstructionsForServers, not applyContextToAgent+ expect(mockLogger.error).toHaveBeenCalledWith(+ '[AgentContext] Failed to get MCP instructions:',+ error,+ );+ });++ it('should handle invalid tools gracefully without throwing', async () => {+ const agent = {+ id: 'test-agent',+ instructions: 'Base',+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ tools: null as any, // Invalid tools - should not crash+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Context',+ mcpManager: mockMCPManager,+ logger: mockLogger,+ });++ // extractMCPServers handles null tools gracefully, returns []+ // getMCPInstructionsForServers returns early with '', so no MCP instructions+ // Agent should still have shared context + base instructions+ expect(agent.instructions).toBe('Context\n\nBase');+ expect(mockMCPManager.formatInstructionsForContext).not.toHaveBeenCalled();+ });++ it('should preserve empty base instructions', async () => {+ const agent = {+ id: 'test-agent',+ instructions: '',+ tools: [+ new DynamicStructuredTool({+ name: `tool${Constants.mcp_delimiter}server1`,+ description: 'Test tool',+ schema: testSchema,+ func: async () => 'result',+ }),+ ],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('MCP only');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Shared',+ mcpManager: mockMCPManager,+ });++ expect(agent.instructions).toBe('Shared\n\nMCP only');+ });++ it('should handle missing instructions field on agent', async () => {+ const agent = {+ id: 'test-agent',+ instructions: undefined,+ tools: [],+ };++ mockMCPManager.formatInstructionsForContext.mockResolvedValue('');++ await applyContextToAgent({+ agent,+ sharedRunContext: 'Context',+ mcpManager: mockMCPManager,+ });++ expect(agent.instructions).toBe('Context');+ });+ });+});diff --git a/packages/api/src/agents/context.ts b/packages/api/src/agents/context.tsnew file mode 100644index 0000000000..cc5c4a6623--- /dev/null+++ b/packages/api/src/agents/context.ts@@ -0,0 +1,148 @@+import { DynamicStructuredTool } from '@langchain/core/tools';+import { Constants } from 'librechat-data-provider';+import type { Agent, TEphemeralAgent } from 'librechat-data-provider';+import type { Logger } from 'winston';+import type { MCPManager } from '~/mcp/MCPManager';++/**+ * Agent type with optional tools array that can contain DynamicStructuredTool or string.+ * For context operations, we only require id and instructions, other Agent fields are optional.+ */+export type AgentWithTools = Pick<Agent, 'id'> &+ Partial<Omit<Agent, 'id' | 'tools'>> & {+ tools?: Array<DynamicStructuredTool | string>;+ };++/**+ * Extracts unique MCP server names from an agent's tools.+ * @param agent - The agent with tools+ * @returns Array of unique MCP server names+ */+export function extractMCPServers(agent: AgentWithTools): string[] {+ if (!agent?.tools?.length) {+ return [];+ }+ const mcpServers = new Set<string>();+ for (let i = 0; i < agent.tools.length; i++) {+ const tool = agent.tools[i];+ if (tool instanceof DynamicStructuredTool && tool.name.includes(Constants.mcp_delimiter)) {+ const serverName = tool.name.split(Constants.mcp_delimiter).pop();+ if (serverName) {+ mcpServers.add(serverName);+ }+ }+ }+ return Array.from(mcpServers);+}++/**+ * Fetches MCP instructions for the given server names.+ * @param {string[]} mcpServers - Array of MCP server names+ * @param {MCPManager} mcpManager - MCP manager instance+ * @param {Logger} [logger] - Optional logger instance+ * @returns {Promise<string>} MCP instructions string, empty if none+ */+export async function getMCPInstructionsForServers(+ mcpServers: string[],+ mcpManager: MCPManager,+ logger?: Logger,+): Promise<string> {+ if (!mcpServers.length) {+ return '';+ }+ try {+ const mcpInstructions = await mcpManager.formatInstructionsForContext(mcpServers);+ if (mcpInstructions && logger) {+ logger.debug('[AgentContext] Fetched MCP instructions for servers:', mcpServers);+ }+ return mcpInstructions || '';+ } catch (error) {+ if (logger) {+ logger.error('[AgentContext] Failed to get MCP instructions:', error);+ }+ return '';+ }+}++/**+ * Builds final instructions for an agent by combining shared run context and agent-specific context.+ * Order: sharedRunContext -> baseInstructions -> mcpInstructions+ *+ * @param {Object} params+ * @param {string} [params.sharedRunContext] - Run-level context shared by all agents (file context, RAG, memory)+ * @param {string} [params.baseInstructions] - Agent's base instructions+ * @param {string} [params.mcpInstructions] - Agent's MCP server instructions+ * @returns {string | undefined} Combined instructions, or undefined if empty+ */+export function buildAgentInstructions({+ sharedRunContext,+ baseInstructions,+ mcpInstructions,+}: {+ sharedRunContext?: string;+ baseInstructions?: string;+ mcpInstructions?: string;+}): string | undefined {+ const parts = [sharedRunContext, baseInstructions, mcpInstructions].filter(Boolean);+ const combined = parts.join('\n\n').trim();+ return combined || undefined;+}++/**+ * Applies run context and MCP instructions to an agent's configuration.+ * Mutates the agent object in place.+ *+ * @param {Object} params+ * @param {Agent} params.agent - The agent to update+ * @param {string} params.sharedRunContext - Run-level shared context+ * @param {MCPManager} params.mcpManager - MCP manager instance+ * @param {Object} [params.ephemeralAgent] - Ephemeral agent config (for MCP override)+ * @param {string} [params.agentId] - Agent ID for logging+ * @param {Logger} [params.logger] - Optional logger instance+ * @returns {Promise<void>}+ */+export async function applyContextToAgent({+ agent,+ sharedRunContext,+ mcpManager,+ ephemeralAgent,+ agentId,+ logger,+}: {+ agent: AgentWithTools;+ sharedRunContext: string;+ mcpManager: MCPManager;+ ephemeralAgent?: TEphemeralAgent;+ agentId?: string;+ logger?: Logger;+}): Promise<void> {+ const baseInstructions = agent.instructions || '';++ try {+ const mcpServers = ephemeralAgent?.mcp?.length ? ephemeralAgent.mcp : extractMCPServers(agent);+ const mcpInstructions = await getMCPInstructionsForServers(mcpServers, mcpManager, logger);++ agent.instructions = buildAgentInstructions({+ sharedRunContext,+ baseInstructions,+ mcpInstructions,+ });++ if (agentId && logger) {+ logger.debug(`[AgentContext] Applied context to agent: ${agentId}`);+ }+ } catch (error) {+ agent.instructions = buildAgentInstructions({+ sharedRunContext,+ baseInstructions,+ mcpInstructions: '',+ });++ if (logger) {+ logger.error(+ `[AgentContext] Failed to apply context to agent${agentId ? ` ${agentId}` : ''}, using base instructions only:`,+ error,+ );+ }+ }+}diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex 5efc22a397..77e7f9e2cc 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -1,5 +1,6 @@export * from './avatars';export * from './chain';+export * from './context';export * from './edges';export * from './initialize';export * from './legacy';diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.tsindex 9e1deb20c1..da773071e7 100644--- a/packages/data-provider/src/types/assistants.ts+++ b/packages/data-provider/src/types/assistants.ts@@ -217,7 +217,7 @@ export type Agent = {description: string | null;created_at: number;avatar: AgentAvatar | null;- instructions: string | null;+ instructions?: string | null;additional_instructions?: string | null;tools?: string[];projectIds?: string[];