@librechat/agents 3.1.66-dev.0 → 3.1.67-dev.0

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 =

package/src/tools/SubagentTool.ts

@@ -0,0 +1,100 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+
+export const SubagentToolName = Constants.SUBAGENT;
+
+export const SubagentToolDescription = `Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result — all intermediate tool calls, reasoning, and context stay isolated.
+
+WHEN TO USE:
+- The task is self-contained and can be described in a single prompt.
+- You want to offload verbose or exploratory work without bloating your own context.
+- A specialized subagent is available for the task domain.
+
+WHAT HAPPENS:
+- A fresh agent is created with the task description as its only input.
+- The subagent runs to completion using its own tools and context.
+- Only the final text response is returned to you.
+
+CONSTRAINTS:
+- subagent_type must match one of the available types listed below.
+- The subagent cannot see your conversation history.`;
+
+const DESCRIPTION_PROP_DESCRIPTION =
+  'Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.';
+
+const SUBAGENT_TYPE_PROP_DESCRIPTION =
+  'Which subagent type to delegate to. Must be one of the available types.';
+
+export const SubagentToolSchema = {
+  type: 'object',
+  properties: {
+    description: {
+      type: 'string',
+      description: DESCRIPTION_PROP_DESCRIPTION,
+    },
+    subagent_type: {
+      type: 'string',
+      description: SUBAGENT_TYPE_PROP_DESCRIPTION,
+    },
+  },
+  required: ['description', 'subagent_type'] as string[],
+} as const;
+
+export const SubagentToolDefinition: LCTool = {
+  name: SubagentToolName,
+  description: SubagentToolDescription,
+  parameters: SubagentToolSchema,
+};
+
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export function buildSubagentToolParams(configs: SubagentConfig[]): {
+  name: string;
+  schema: JsonSchemaType;
+  description: string;
+} {
+  const types = configs.map((c) => c.type);
+  const typeDescriptions = configs
+    .map((c) => `- "${c.type}" (${c.name}): ${c.description}`)
+    .join('\n');
+
+  return {
+    name: SubagentToolName,
+    schema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: DESCRIPTION_PROP_DESCRIPTION,
+        },
+        subagent_type: {
+          type: 'string',
+          enum: types,
+          description: `${SUBAGENT_TYPE_PROP_DESCRIPTION} Available: ${types.join(', ')}.`,
+        },
+      },
+      required: ['description', 'subagent_type'],
+    },
+    description: `${SubagentToolDescription}\n\nAvailable types:\n${typeDescriptions}`,
+  };
+}
+
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export function createSubagentToolDefinition(
+  configs: SubagentConfig[]
+): LCTool {
+  const params = buildSubagentToolParams(configs);
+  return {
+    name: params.name,
+    description: params.description,
+    parameters: params.schema,
+  };
+}