@librechat/agents 3.1.66 → 3.1.67-dev.0

package/src/scripts/multi-agent-subagent.ts

@@ -0,0 +1,246 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Manual verification script for the subagent primitive.
+ *
+ * Configures a supervisor agent with two subagent types (researcher, coder),
+ * sends a query, and confirms:
+ * 1. The parent agent delegates to a subagent via the `subagent` tool
+ * 2. The child executes with isolated context (fresh message history)
+ * 3. Only the filtered text result returns to the parent
+ * 4. The parent incorporates the result and responds
+ *
+ * Usage:
+ *   OPENAI_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts
+ *
+ * Or with Anthropic:
+ *   ANTHROPIC_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts --provider anthropic
+ */
+
+const useAnthropic =
+  process.argv.includes('--provider') &&
+  process.argv[process.argv.indexOf('--provider') + 1] === 'anthropic';
+
+const provider = useAnthropic ? Providers.ANTHROPIC : Providers.OPENAI;
+const apiKey = useAnthropic
+  ? process.env.ANTHROPIC_API_KEY
+  : process.env.OPENAI_API_KEY;
+const modelName = useAnthropic ? 'claude-sonnet-4-20250514' : 'gpt-5.4';
+
+if (!apiKey) {
+  console.error(
+    `Missing ${useAnthropic ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY'} environment variable`
+  );
+  process.exit(1);
+}
+
+async function testSubagentPrimitive() {
+  console.log('=== Subagent Primitive Manual Verification ===\n');
+  console.log(`Provider: ${provider}`);
+  console.log(`Model: ${modelName}\n`);
+
+  const { aggregateContent } = createContentAggregator();
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider,
+    clientOptions: { modelName, apiKey },
+    instructions: `You are a supervisor agent. You have access to specialized subagents.
+
+When the user asks a research question, delegate it to the "researcher" subagent.
+When the user asks for code, delegate it to the "coder" subagent.
+
+After receiving the subagent's result, synthesize it into a clear final answer for the user.
+Always use a subagent for research or coding tasks — do not answer directly.`,
+    maxContextTokens: 16000,
+    subagentConfigs: [
+      {
+        type: 'researcher',
+        name: 'Research Specialist',
+        description:
+          'Researches topics and provides detailed summaries with sources.',
+        agentInputs: {
+          agentId: 'researcher',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a research specialist working in an isolated context.
+You receive a single task description and must answer it thoroughly.
+Be concise but comprehensive. Include key facts and details.`,
+          maxContextTokens: 8000,
+        },
+      },
+      {
+        type: 'coder',
+        name: 'Coding Specialist',
+        description:
+          'Writes, reviews, and explains code in any programming language.',
+        agentInputs: {
+          agentId: 'coder',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a coding specialist working in an isolated context.
+You receive a single task description and must provide working code.
+Include brief explanations. Use clean, idiomatic code.`,
+          maxContextTokens: 8000,
+        },
+      },
+    ],
+  };
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStepDeltaEvent,
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.MessageDeltaEvent,
+        });
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-manual-${Date.now()}`,
+    graphConfig: {
+      type: 'standard',
+      agents: [parentAgent],
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  console.log('--- Run created ---');
+  console.log(
+    `Subagent tool present: ${
+      (
+        (run.Graph as import('@/graphs/Graph').StandardGraph).agentContexts.get(
+          'supervisor'
+        )?.graphTools as t.GenericTool[] | undefined
+      )?.some((t) => 'name' in t && t.name === Constants.SUBAGENT) ?? false
+    }\n`
+  );
+
+  const conversationHistory: BaseMessage[] = [];
+
+  // Turn 1: Research question (should delegate to researcher subagent)
+  console.log('=== Turn 1: Research Question ===\n');
+  console.log(
+    'User: What are the three laws of thermodynamics? Explain briefly.\n'
+  );
+
+  const userMessage = new HumanMessage(
+    'What are the three laws of thermodynamics? Explain briefly.'
+  );
+  conversationHistory.push(userMessage);
+
+  const callerConfig = {
+    configurable: { thread_id: 'subagent-verify' },
+    streamMode: 'values' as const,
+    version: 'v2' as const,
+  };
+
+  console.log('--- Streaming response ---\n');
+  const result = await run.processStream(
+    { messages: conversationHistory },
+    callerConfig
+  );
+
+  const runMessages = run.getRunMessages();
+  console.log('\n\n--- Run Messages ---\n');
+
+  if (runMessages) {
+    for (const msg of runMessages) {
+      const type = msg._getType();
+      if (type === 'tool') {
+        const name = 'name' in msg ? msg.name : 'unknown';
+        const rawContent =
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content);
+        const content = rawContent.slice(0, 200);
+        const truncated = rawContent.length > 200 ? '...' : '';
+        console.log(`[ToolMessage] name=${name}`);
+        console.log(`  content: ${content}${truncated}\n`);
+      } else if (type === 'ai') {
+        const content =
+          typeof msg.content === 'string'
+            ? msg.content.slice(0, 300)
+            : JSON.stringify(msg.content).slice(0, 300);
+        const toolCalls = 'tool_calls' in msg ? msg.tool_calls : undefined;
+        console.log(`[AIMessage]`);
+        if (toolCalls && Array.isArray(toolCalls) && toolCalls.length > 0) {
+          for (const tc of toolCalls) {
+            console.log(
+              `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 100)}...)`
+            );
+          }
+        }
+        console.log(
+          `  content: ${content}${content.length >= 300 ? '...' : ''}\n`
+        );
+      }
+    }
+
+    const subagentToolMessages = runMessages.filter(
+      (msg) =>
+        msg._getType() === 'tool' &&
+        'name' in msg &&
+        msg.name === Constants.SUBAGENT
+    );
+    console.log(`\n--- Verification ---`);
+    console.log(`Subagent tool calls found: ${subagentToolMessages.length}`);
+    console.log(`Total run messages: ${runMessages.length}`);
+    console.log(`Result content parts: ${result?.length ?? 0}`);
+
+    if (subagentToolMessages.length > 0) {
+      console.log(
+        '\nSUCCESS: Subagent was invoked and returned a filtered result.'
+      );
+      console.log(
+        'The child context was isolated — only the final text came back.'
+      );
+    } else {
+      console.log('\nNOTE: No subagent tool calls detected.');
+      console.log('The LLM may have answered directly without delegating.');
+    }
+  }
+
+  console.log('\n=== Done ===');
+}
+
+testSubagentPrimitive().catch(console.error);

package/src/specs/subagent.test.ts

@@ -0,0 +1,305 @@
+import { HumanMessage } from '@langchain/core/messages';
+import { FakeListChatModel } from '@langchain/core/utils/testing';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Run } from '@/run';
+import {
+  Constants,
+  GraphEvents,
+  Providers,
+  ToolEndHandler,
+  ModelEndHandler,
+  StandardGraph,
+} from '@/index';
+import * as providers from '@/llm/providers';
+
+const CHILD_RESPONSE = 'Research result: Paris is the capital of France.';
+
+const callerConfig: Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  streamMode: string;
+} = {
+  configurable: { thread_id: 'subagent-test-thread' },
+  streamMode: 'values',
+  version: 'v2' as const,
+};
+
+const createParentAgent = (): t.AgentInputs => ({
+  agentId: 'parent',
+  provider: Providers.OPENAI,
+  clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+  instructions:
+    'You are a supervisor. Delegate research tasks using the subagent tool.',
+  maxContextTokens: 8000,
+  subagentConfigs: [
+    {
+      type: 'researcher',
+      name: 'Research Agent',
+      description: 'Researches and summarizes information',
+      agentInputs: {
+        agentId: 'researcher',
+        provider: Providers.OPENAI,
+        clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+        instructions: 'You are a research agent. Answer concisely.',
+        maxContextTokens: 8000,
+      },
+    },
+  ],
+});
+
+describe('Subagent Integration', () => {
+  jest.setTimeout(30000);
+
+  let getChatModelClassSpy: jest.SpyInstance;
+  const originalGetChatModelClass = providers.getChatModelClass;
+
+  beforeEach(() => {
+    getChatModelClassSpy = jest
+      .spyOn(providers, 'getChatModelClass')
+      .mockImplementation(((provider: Providers) => {
+        if (provider === Providers.OPENAI) {
+          return class extends FakeListChatModel {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(_options: any) {
+              super({ responses: [CHILD_RESPONSE] });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          } as any;
+        }
+        return originalGetChatModelClass(provider);
+      }) as typeof providers.getChatModelClass);
+  });
+
+  afterEach(() => {
+    getChatModelClassSpy.mockRestore();
+  });
+
+  it('should create subagent tool on agent context', async () => {
+    const run = await Run.create<t.IState>({
+      runId: `subagent-test-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    expect(run.Graph).toBeDefined();
+    const parentContext = (run.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    expect(parentContext).toBeDefined();
+    expect(parentContext?.graphTools).toBeDefined();
+
+    const subagentTool = (parentContext?.graphTools as t.GenericTool[]).find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should execute subagent and return filtered result to parent', async () => {
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `subagent-exec-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+    });
+
+    const subagentToolCall: ToolCall = {
+      id: 'call_subagent_1',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'What is the capital of France?',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call',
+    };
+
+    run.Graph?.overrideTestModel(
+      [
+        'Let me delegate this research task.',
+        `Based on the research: ${CHILD_RESPONSE}`,
+      ],
+      10,
+      [subagentToolCall]
+    );
+
+    const result = await run.processStream(
+      { messages: [new HumanMessage('What is the capital of France?')] },
+      callerConfig
+    );
+
+    expect(result).toBeDefined();
+
+    const runMessages = run.getRunMessages();
+    expect(runMessages).toBeDefined();
+    expect(runMessages!.length).toBeGreaterThan(0);
+
+    const toolMessages = runMessages!.filter(
+      (msg) => msg._getType() === 'tool'
+    );
+    const subagentResult = toolMessages.find(
+      (msg) => 'name' in msg && msg.name === Constants.SUBAGENT
+    );
+    expect(subagentResult).toBeDefined();
+    expect(String(subagentResult!.content)).toContain('Paris');
+  });
+
+  it('should not create subagent tool when no subagentConfigs', async () => {
+    const agentWithoutSubagents: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Plain agent without subagents.',
+      maxContextTokens: 8000,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `no-subagent-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagents],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get('plain');
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should handle self-spawn subagent config', async () => {
+    const agentWithSelfSpawn: t.AgentInputs = {
+      agentId: 'self-parent',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Agent with self-spawn for context isolation.',
+      maxContextTokens: 8000,
+      subagentConfigs: [
+        {
+          type: 'isolated',
+          name: 'Isolated Worker',
+          description: 'Runs a task with isolated context',
+          self: true,
+        },
+      ],
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `self-spawn-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSelfSpawn],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'self-parent'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should not create subagent tool when maxSubagentDepth is 0', async () => {
+    const agentWithZeroDepth: t.AgentInputs = {
+      ...createParentAgent(),
+      agentId: 'zero-depth',
+      maxSubagentDepth: 0,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `zero-depth-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithZeroDepth],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'zero-depth'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should account for subagent tool schema in toolSchemaTokens', async () => {
+    /** Simple char-count tokenizer — deterministic, lets us assert presence. */
+    const tokenCounter: t.TokenCounter = (message) => {
+      const content = message.content;
+      if (typeof content === 'string') return content.length;
+      if (Array.isArray(content)) return JSON.stringify(content).length;
+      return JSON.stringify(content).length;
+    };
+
+    const agentWithSubagent = createParentAgent();
+    const runWith = await Run.create<t.IState>({
+      runId: `with-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const agentWithoutSubagent: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions:
+        'You are a supervisor. Delegate research tasks using the subagent tool.',
+      maxContextTokens: 8000,
+    };
+    const runWithout = await Run.create<t.IState>({
+      runId: `without-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const contextWith = (runWith.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    const contextWithout = (
+      runWithout.Graph as StandardGraph
+    ).agentContexts.get('plain');
+
+    await contextWith?.tokenCalculationPromise;
+    await contextWithout?.tokenCalculationPromise;
+
+    /** Subagent tool schema is ~600 chars; expect measurable difference. */
+    expect(contextWith!.toolSchemaTokens).toBeGreaterThan(
+      contextWithout!.toolSchemaTokens
+    );
+  });
+});

package/src/summarization/node.ts

@@ -7,6 +7,7 @@ import {
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
 import { ContentTypes, GraphEvents, StepTypes, Providers } from '@/common';
@@ -17,6 +18,7 @@ import { getMaxOutputTokensKey } from '@/llm/request';
 import { addCacheControl } from '@/messages/cache';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
+import { executeHooks } from '@/hooks';
 
 const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
 
@@ -530,6 +532,35 @@ async function dispatchCompletionEvents(params: {
     );
   }
 
+  const sessionId = graph.runId ?? '';
+  if (graph.hookRegistry?.hasHookFor('PostCompact', sessionId) === true) {
+    const threadId = (
+      runnableConfig?.configurable as Record<string, unknown> | undefined
+    )?.thread_id as string | undefined;
+    const firstBlock = summaryBlock.content?.[0];
+    const summaryText =
+      firstBlock != null &&
+      typeof firstBlock === 'object' &&
+      'text' in firstBlock &&
+      typeof firstBlock.text === 'string'
+        ? firstBlock.text
+        : '';
+    await executeHooks({
+      registry: graph.hookRegistry,
+      input: {
+        hook_event_name: 'PostCompact',
+        runId: sessionId,
+        threadId,
+        agentId,
+        summary: summaryText,
+        messagesAfterCount: 0,
+      },
+      sessionId,
+    }).catch(() => {
+      /* PostCompact is observational — swallow errors */
+    });
+  }
+
   agentContext.rebuildTokenMapAfterSummarization({});
 }
 
@@ -545,6 +576,7 @@ interface CreateSummarizeNodeParams {
     config?: RunnableConfig;
     runId?: string;
     isMultiAgent: boolean;
+    hookRegistry?: HookRegistry;
     dispatchRunStep: (
       runStep: t.RunStep,
       config?: RunnableConfig
@@ -650,6 +682,27 @@ export function createSummarizeNode({
       );
     }
 
+    const sessionId = graph.runId ?? '';
+    if (graph.hookRegistry?.hasHookFor('PreCompact', sessionId) === true) {
+      const threadId = (
+        runnableConfig?.configurable as Record<string, unknown> | undefined
+      )?.thread_id as string | undefined;
+      await executeHooks({
+        registry: graph.hookRegistry,
+        input: {
+          hook_event_name: 'PreCompact',
+          runId: sessionId,
+          threadId,
+          agentId: request.agentId,
+          messagesBeforeCount: messagesToRefine.length,
+          trigger: agentContext.summarizationConfig?.trigger?.type ?? 'default',
+        },
+        sessionId,
+      }).catch(() => {
+        /* PreCompact is observational — swallow errors */
+      });
+    }
+
     const isSelfSummarizeModel =
       clientConfig.provider === (agentContext.provider as string);
     const hasPromptCache =