@librechat/agents 3.4.1 → 3.4.2

package/src/specs/graph-subagent.test.ts

@@ -0,0 +1,322 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { AIMessageChunk } from '@langchain/core/messages';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import { FakeListChatModel } from '@langchain/core/utils/testing';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { GraphSubagentConfig } from '@/types';
+import type * as t from '@/types';
+import { createFakeStreamingLLM } from '@/llm/fake';
+import { Constants, Providers } from '@/common';
+import { StandardGraph } from '@/graphs/Graph';
+import { Run } from '@/run';
+
+const invokeConfig: RunnableConfig = {
+  configurable: { thread_id: 'graph-subagent-test' },
+};
+
+const usage = {
+  input_tokens: 5,
+  output_tokens: 3,
+  total_tokens: 8,
+};
+
+class UsageFakeChatModel extends FakeListChatModel {
+  constructor() {
+    super({ responses: ['member response'] });
+  }
+
+  override async *_streamResponseChunks(
+    ...args: Parameters<FakeListChatModel['_streamResponseChunks']>
+  ): ReturnType<FakeListChatModel['_streamResponseChunks']> {
+    yield* super._streamResponseChunks(...args);
+    yield new ChatGenerationChunk({
+      text: '',
+      message: new AIMessageChunk({
+        content: '',
+        usage_metadata: { ...usage },
+      }),
+    });
+  }
+}
+
+class LoopingFakeChatModel extends FakeListChatModel {
+  private invocationCount = 0;
+
+  constructor() {
+    super({ responses: ['unused'] });
+  }
+
+  override async *_streamResponseChunks(
+    ..._args: Parameters<FakeListChatModel['_streamResponseChunks']>
+  ): ReturnType<FakeListChatModel['_streamResponseChunks']> {
+    this.invocationCount++;
+    if (this.invocationCount <= 2) {
+      yield new ChatGenerationChunk({
+        text: '',
+        message: new AIMessageChunk({
+          content: '',
+          tool_call_chunks: [
+            {
+              name: 'loop_tool',
+              args: '{}',
+              id: `loop-${this.invocationCount}`,
+              index: 0,
+              type: 'tool_call_chunk',
+            },
+          ],
+        }),
+      });
+      return;
+    }
+    yield new ChatGenerationChunk({
+      text: 'escaped member turn limit',
+      message: new AIMessageChunk('escaped member turn limit'),
+    });
+  }
+}
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  clientOptions: { modelName: `${agentId}-model`, apiKey: 'test-key' },
+  instructions: `You are ${agentId}.`,
+});
+
+const makeGraphConfig = (): GraphSubagentConfig => ({
+  kind: 'graph',
+  type: 'research-team',
+  name: 'Research Team',
+  description: 'Coordinates parallel research and synthesis.',
+  entryAgentId: 'coordinator',
+  resultAgentId: 'synthesizer',
+  agents: [
+    makeAgent('coordinator'),
+    makeAgent('left'),
+    makeAgent('right'),
+    makeAgent('synthesizer'),
+  ],
+  edges: [
+    {
+      from: 'coordinator',
+      to: ['left', 'right'],
+      edgeType: 'direct',
+    },
+    {
+      from: ['left', 'right'],
+      to: 'synthesizer',
+      edgeType: 'direct',
+    },
+  ],
+});
+
+const createRun = async (
+  graphConfig: GraphSubagentConfig,
+  overrides: Partial<t.RunConfig> = {}
+): Promise<Run<t.IState>> =>
+  Run.create<t.IState>({
+    runId: `graph-subagent-${Date.now()}-${Math.random()}`,
+    graphConfig: {
+      type: 'standard',
+      agents: [
+        {
+          ...makeAgent('parent'),
+          maxSubagentDepth: 2,
+          subagentConfigs: [graphConfig],
+        },
+      ],
+    },
+    returnContent: true,
+    skipCleanup: true,
+    ...overrides,
+  });
+
+const getGraphSubagentTool = (run: Run<t.IState>): t.GenericTool => {
+  const tools = (run.Graph as StandardGraph).agentContexts.get('parent')
+    ?.graphTools as t.GenericTool[] | undefined;
+  const tool = tools?.find(
+    (candidate) => 'name' in candidate && candidate.name === Constants.SUBAGENT
+  );
+  if (tool == null) {
+    throw new Error('Expected graph subagent tool');
+  }
+  return tool;
+};
+
+describe('Graph subagent integration', () => {
+  it('runs a convergent direct DAG and returns only the designated result', async () => {
+    const graphConfig = { ...makeGraphConfig(), maxTurns: 1 };
+    const run = await createRun(graphConfig);
+    (run.Graph as StandardGraph).setSubagentModelOverride(
+      createFakeStreamingLLM({
+        responses: [
+          'coordinator plan',
+          'left research',
+          'right research',
+          'synthesized answer',
+        ],
+      })
+    );
+
+    const result = await getGraphSubagentTool(run).invoke(
+      {
+        description: 'Research and synthesize the question.',
+        subagent_type: 'research-team',
+      },
+      invokeConfig
+    );
+
+    expect(result).toBe('synthesized answer');
+  });
+
+  it('does not fall back to worker text when the result member is textless', async () => {
+    const graphConfig: GraphSubagentConfig = {
+      ...makeGraphConfig(),
+      agents: [makeAgent('worker'), makeAgent('result')],
+      edges: [{ from: 'worker', to: 'result', edgeType: 'direct' }],
+      entryAgentId: 'worker',
+      resultAgentId: 'result',
+    };
+    const run = await createRun(graphConfig);
+    (run.Graph as StandardGraph).setSubagentModelOverride(
+      createFakeStreamingLLM({ responses: ['worker text', ''] })
+    );
+
+    const result = await getGraphSubagentTool(run).invoke(
+      {
+        description: 'Complete the two-step task.',
+        subagent_type: 'research-team',
+      },
+      invokeConfig
+    );
+
+    expect(result).toBe('Task completed');
+  });
+
+  it('keeps each member turn budget independent from the outer graph budget', async () => {
+    const loopTool = tool(async (): Promise<string> => 'continue', {
+      name: 'loop_tool',
+      description: 'Continue the member loop.',
+      schema: z.object({}),
+    });
+    const graphConfig: GraphSubagentConfig = {
+      ...makeGraphConfig(),
+      maxTurns: 1,
+      agents: [
+        { ...makeAgent('entry'), graphTools: [loopTool] },
+        makeAgent('result'),
+      ],
+      edges: [{ from: 'entry', to: 'result', edgeType: 'direct' }],
+      entryAgentId: 'entry',
+      resultAgentId: 'result',
+    };
+    const run = await createRun(graphConfig);
+    (run.Graph as StandardGraph).setSubagentModelOverride(
+      new LoopingFakeChatModel()
+    );
+
+    const output = await getGraphSubagentTool(run).invoke(
+      {
+        description: 'Try to exceed the member turn budget.',
+        subagent_type: 'research-team',
+      },
+      invokeConfig
+    );
+
+    expect(output).toMatch(/Subagent error: Recursion limit of 3 reached/);
+  });
+
+  it('fails closed when human-in-the-loop is enabled', async () => {
+    const run = await createRun(makeGraphConfig(), {
+      humanInTheLoop: { enabled: true },
+    });
+
+    const result = await getGraphSubagentTool(run).invoke(
+      {
+        description: 'Do not start this graph.',
+        subagent_type: 'research-team',
+      },
+      invokeConfig
+    );
+
+    expect(result).toBe(
+      'Error: Human-in-the-loop execution is not yet supported for graph subagents.'
+    );
+  });
+
+  it('attributes usage to each graph member', async () => {
+    const graphConfig: GraphSubagentConfig = {
+      ...makeGraphConfig(),
+      agents: [makeAgent('entry'), makeAgent('worker'), makeAgent('result')],
+      edges: [
+        { from: 'entry', to: 'worker', edgeType: 'direct' },
+        { from: 'worker', to: 'result', edgeType: 'direct' },
+      ],
+      entryAgentId: 'entry',
+      resultAgentId: 'result',
+    };
+    const usageEvents: t.SubagentUsageEvent[] = [];
+    const run = await createRun(graphConfig, {
+      subagentUsageSink: (event) => {
+        usageEvents.push(event);
+      },
+    });
+    (run.Graph as StandardGraph).setSubagentModelOverride(
+      new UsageFakeChatModel()
+    );
+
+    await getGraphSubagentTool(run).invoke(
+      {
+        description: 'Complete the measured graph.',
+        subagent_type: 'research-team',
+      },
+      invokeConfig
+    );
+
+    expect(usageEvents).toHaveLength(3);
+    expect(
+      usageEvents.map((event) => ({
+        memberAgentId: event.memberAgentId,
+        model: event.model,
+        provider: event.provider,
+        subagentKind: event.subagentKind,
+      }))
+    ).toEqual([
+      {
+        memberAgentId: 'entry',
+        model: 'entry-model',
+        provider: Providers.OPENAI,
+        subagentKind: 'graph',
+      },
+      {
+        memberAgentId: 'worker',
+        model: 'worker-model',
+        provider: Providers.OPENAI,
+        subagentKind: 'graph',
+      },
+      {
+        memberAgentId: 'result',
+        model: 'result-model',
+        provider: Providers.OPENAI,
+        subagentKind: 'graph',
+      },
+    ]);
+    expect(
+      new Set(usageEvents.map((event) => event.subagentAgentId)).size
+    ).toBe(1);
+    const rootRunId = (run.Graph as StandardGraph).runId;
+    for (const event of usageEvents) {
+      expect(event).toMatchObject({
+        runId: rootRunId,
+        parentRunId: rootRunId,
+        depth: 1,
+      });
+      expect(event.ancestry).toHaveLength(1);
+      expect(event.ancestry?.[0]).toMatchObject({
+        subagentType: 'research-team',
+        subagentKind: 'graph',
+        parentRunId: rootRunId,
+      });
+    }
+  });
+});

package/src/specs/langfuse-routing.integration.test.ts

@@ -319,6 +319,50 @@ function createAgent(tenantId: string): t.AgentInputs {
   };
 }
 
+function createGraphSubagentParent(tenantId: string): t.AgentInputs {
+  const makeMember = (agentId: string): t.AgentInputs => ({
+    agentId,
+    name: `${agentId} ${tenantId}`,
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+    instructions: `Complete the ${agentId} stage.`,
+    maxContextTokens: 8000,
+  });
+  return {
+    ...makeMember('parent'),
+    maxSubagentDepth: 1,
+    subagentConfigs: [
+      {
+        kind: 'graph',
+        type: 'research-team',
+        name: 'Research Team',
+        description: 'Runs a bounded research chain.',
+        agents: [
+          makeMember('entry'),
+          makeMember('worker'),
+          makeMember('result'),
+        ],
+        edges: [
+          {
+            from: 'entry',
+            to: 'worker',
+            edgeType: 'direct',
+            prompt: 'Proceed to worker.',
+          },
+          {
+            from: 'worker',
+            to: 'result',
+            edgeType: 'direct',
+            prompt: 'Proceed to result.',
+          },
+        ],
+        entryAgentId: 'entry',
+        resultAgentId: 'result',
+      },
+    ],
+  };
+}
+
 async function runTenantFlow(tenantId: string): Promise<void> {
   const runId = `routing-${tenantId}`;
   const run = await Run.create<t.IState>({
@@ -382,6 +426,49 @@ async function runTenantFlow(tenantId: string): Promise<void> {
   });
 }
 
+async function runGraphSubagentTenantFlow(tenantId: string): Promise<void> {
+  const runId = `routing-graph-${tenantId}`;
+  const run = await Run.create<t.IState>({
+    runId,
+    graphConfig: {
+      type: 'standard',
+      agents: [createGraphSubagentParent(tenantId)],
+    },
+    langfuse: tenantLangfuse(tenantId),
+    returnContent: true,
+    skipCleanup: true,
+  });
+  run.Graph?.overrideTestModel(
+    [
+      `Delegating graph work for ${tenantId}.`,
+      `Graph work complete for ${tenantId}.`,
+    ],
+    1,
+    [
+      {
+        id: `call_graph_subagent_${tenantId}`,
+        name: Constants.SUBAGENT,
+        args: {
+          description: `Run the research chain for ${tenantId}.`,
+          subagent_type: 'research-team',
+        },
+        type: 'tool_call',
+      },
+    ]
+  );
+
+  await run.processStream(
+    { messages: [new HumanMessage(`Run graph work for ${tenantId}`)] },
+    {
+      ...callerConfig,
+      configurable: {
+        thread_id: `graph-thread-${tenantId}`,
+        user_id: `graph-user-${tenantId}`,
+      },
+    }
+  );
+}
+
 const compactingTokenCounter: t.TokenCounter = (message) => {
   if (message._getType() === 'system') {
     return 1;
@@ -454,7 +541,7 @@ describe('Langfuse per-run routing integration', () => {
       .spyOn(providers, 'getChatModelClass')
       .mockImplementation(((provider: Providers) => {
         if (provider === Providers.OPENAI) {
-          return class extends FakeListChatModel {
+          return class RoutingProviderFakeChatModel extends FakeListChatModel {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             constructor(_options: any) {
               super({ responses: ['provider response'] });
@@ -531,6 +618,38 @@ describe('Langfuse per-run routing integration', () => {
     }
   });
 
+  it('keeps graph-subagent member spans in the owning tenant trace', async () => {
+    await Promise.all([
+      runGraphSubagentTenantFlow('graph-tenant-a'),
+      runGraphSubagentTenantFlow('graph-tenant-b'),
+    ]);
+
+    for (const tenantId of ['graph-tenant-a', 'graph-tenant-b']) {
+      const otherTenantId =
+        tenantId === 'graph-tenant-a' ? 'graph-tenant-b' : 'graph-tenant-a';
+      const starts = startsForTenant(tenantId);
+      const traceId = traceIdFromSeed(`routing-graph-${tenantId}`);
+
+      expectTenantCredentials(starts, tenantId);
+      expectOnlyTraceIds(starts, [traceId]);
+      expectNamedSpansUseTraceId({
+        starts,
+        traceId,
+        names: [
+          `LibreChat Agent: parent ${tenantId}`,
+          'FakeChatModel',
+          'subagent',
+        ],
+      });
+      expect(
+        starts.filter(
+          (record) => record.name === 'RoutingProviderFakeChatModel'
+        )
+      ).toHaveLength(3);
+      expectNoCrossTenantTrace({ tenantId, otherTenantId, traceId });
+    }
+  });
+
   it('routes parallel summarization spans to each run config', async () => {
     await Promise.all([
       runTenantSummarizationFlow('tenant-a'),

package/src/specs/subagent.test.ts

@@ -5,8 +5,8 @@ import {
   AIMessageChunk,
   HumanMessage,
 } from '@langchain/core/messages';
+import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { UsageMetadata } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import {
@@ -371,6 +371,8 @@ describe('Subagent Integration', () => {
       }
     );
     const parentUpdateHandler = jest.fn();
+    const rootModelEndHandler = jest.fn();
+    const nestedUsageEvents: t.SubagentUsageEvent[] = [];
     let specialistToolDefinitions: t.LCTool[] | undefined;
     let forwardedToolResults: t.ToolExecuteResult[] | undefined;
 
@@ -409,7 +411,12 @@ describe('Subagent Integration', () => {
               const invokeOptions = options as
                 | { callbacks?: unknown[] }
                 | undefined;
-              const forwarder = (invokeOptions?.callbacks ?? [])[0] as
+              const callbacks = invokeOptions?.callbacks ?? [];
+              const forwarder = callbacks.find(
+                (callback) =>
+                  typeof (callback as { handleCustomEvent?: unknown })
+                    .handleCustomEvent === 'function'
+              ) as
                 | {
                     handleCustomEvent?: (
                       eventName: string,
@@ -418,6 +425,27 @@ describe('Subagent Integration', () => {
                     ) => Promise<void> | void;
                   }
                 | undefined;
+              const usageHandler = callbacks.find(
+                (callback) =>
+                  typeof (callback as { handleLLMEnd?: unknown })
+                    .handleLLMEnd === 'function'
+              ) as
+                | {
+                    handleChatModelStart?: (
+                      llm: unknown,
+                      messages: BaseMessage[][],
+                      runId: string,
+                      parentRunId?: string,
+                      extraParams?: unknown,
+                      tags?: string[],
+                      metadata?: Record<string, unknown>
+                    ) => Promise<void> | void;
+                    handleLLMEnd?: (
+                      output: unknown,
+                      runId: string
+                    ) => Promise<void> | void;
+                  }
+                | undefined;
               if (forwarder?.handleCustomEvent != null) {
                 forwardedToolResults = await new Promise<t.ToolExecuteResult[]>(
                   (resolve, reject) => {
@@ -442,6 +470,38 @@ describe('Subagent Integration', () => {
                   'specialist-run'
                 );
               }
+              await usageHandler?.handleChatModelStart?.(
+                {},
+                [[]],
+                'specialist-model-call',
+                undefined,
+                undefined,
+                undefined,
+                {
+                  agentId: 'specialist',
+                  ls_model_name: 'gpt-4o-mini',
+                }
+              );
+              await usageHandler?.handleLLMEnd?.(
+                {
+                  generations: [
+                    [
+                      {
+                        text: 'specialist done',
+                        message: new AIMessage({
+                          content: 'specialist done',
+                          usage_metadata: {
+                            input_tokens: 5,
+                            output_tokens: 3,
+                            total_tokens: 8,
+                          },
+                        }),
+                      },
+                    ],
+                  ],
+                },
+                'specialist-model-call'
+              );
               return { messages: [new AIMessage('specialist done')] };
             }),
           } as unknown as ReturnType<StandardGraph['createWorkflow']>;
@@ -492,17 +552,22 @@ describe('Subagent Integration', () => {
     };
 
     try {
+      const rootRunId = `nested-event-tools-${Date.now()}`;
       const run = await Run.create<t.IState>({
-        runId: `nested-event-tools-${Date.now()}`,
+        runId: rootRunId,
         graphConfig: { type: 'standard', agents: [rootAgent] },
         customHandlers: {
           [GraphEvents.ON_TOOL_EXECUTE]: { handle: parentToolHandler },
+          [GraphEvents.CHAT_MODEL_END]: { handle: rootModelEndHandler },
           [GraphEvents.ON_SUBAGENT_UPDATE]: {
             handle: parentUpdateHandler,
           },
         },
         returnContent: true,
         skipCleanup: true,
+        subagentUsageSink: (event) => {
+          nestedUsageEvents.push(event);
+        },
       });
       const rootContext = (run.Graph as StandardGraph).agentContexts.get(
         'root'
@@ -530,7 +595,68 @@ describe('Subagent Integration', () => {
         ([, data]) => (data as t.SubagentUpdateEvent).subagentType
       );
       expect(forwardedSubagentTypes).toContain('router');
-      expect(forwardedSubagentTypes).not.toContain('specialist');
+      expect(forwardedSubagentTypes).toContain('specialist');
+      const specialistStepUpdates = parentUpdateHandler.mock.calls.filter(
+        ([, data]) => {
+          const event = data as t.SubagentUpdateEvent;
+          return (
+            event.subagentType === 'specialist' &&
+            (event.data as { id?: string } | undefined)?.id ===
+              'specialist-step'
+          );
+        }
+      );
+      expect(specialistStepUpdates).toHaveLength(1);
+      const routerEvent = parentUpdateHandler.mock.calls
+        .map(([, data]) => data as t.SubagentUpdateEvent)
+        .find((event) => event.subagentType === 'router');
+      const specialistEvent =
+        specialistStepUpdates[0][1] as t.SubagentUpdateEvent;
+      expect(routerEvent).toMatchObject({
+        runId: rootRunId,
+        parentRunId: rootRunId,
+        depth: 1,
+      });
+      expect(routerEvent?.ancestry?.map((entry) => entry.subagentType)).toEqual(
+        ['router']
+      );
+      expect(specialistEvent).toMatchObject({
+        runId: rootRunId,
+        parentRunId: routerEvent?.subagentRunId,
+        depth: 2,
+      });
+      expect(
+        specialistEvent.ancestry?.map((entry) => ({
+          type: entry.subagentType,
+          kind: entry.subagentKind,
+        }))
+      ).toEqual([
+        { type: 'router', kind: 'agent' },
+        { type: 'specialist', kind: 'agent' },
+      ]);
+      expect(nestedUsageEvents).toHaveLength(1);
+      expect(rootModelEndHandler).not.toHaveBeenCalled();
+      expect(nestedUsageEvents[0]).toMatchObject({
+        runId: rootRunId,
+        parentRunId: routerEvent?.subagentRunId,
+        subagentType: 'specialist',
+        subagentAgentId: 'specialist',
+        depth: 2,
+        usage: {
+          input_tokens: 5,
+          output_tokens: 3,
+          total_tokens: 8,
+        },
+      });
+      expect(
+        nestedUsageEvents[0].ancestry?.map((entry) => ({
+          type: entry.subagentType,
+          kind: entry.subagentKind,
+        }))
+      ).toEqual([
+        { type: 'router', kind: 'agent' },
+        { type: 'specialist', kind: 'agent' },
+      ]);
     } finally {
       createWorkflowSpy.mockRestore();
     }

package/src/tools/SubagentTool.ts

@@ -5,7 +5,7 @@ import { Constants } from '@/common';
 
 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.
+export const SubagentToolDescription = `Delegate a task to a specialized subagent or bounded agent team that runs in an isolated context window. The delegated execution returns only its designated 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.
@@ -13,9 +13,9 @@ WHEN TO USE:
 - 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.
+- A fresh agent or configured agent graph is created with the task description as its only input.
+- The delegated agent or team runs to completion using isolated tools and context.
+- Only the single agent's final response or the graph's designated result-agent response is returned to you.
 
 CONSTRAINTS:
 - subagent_type must match one of the available types listed below.