@librechat/agents 3.4.1 → 3.4.2

package/src/graphs/__tests__/createGraph.test.ts

@@ -0,0 +1,206 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { GraphFactory, GraphFactoryRequest } from '@/graphs/graphFactory';
+import type * as t from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { createFakeStreamingLLM } from '@/llm/fake';
+import { createGraph } from '@/graphs/createGraph';
+import { Constants, Providers } from '@/common';
+import { StandardGraph } from '@/graphs/Graph';
+
+const invokeConfig: RunnableConfig = {
+  configurable: { thread_id: 'graph-factory-test' },
+};
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  instructions: `You are ${agentId}.`,
+});
+
+const getSubagentTool = (
+  graph: StandardGraph,
+  agentId: string
+): t.GenericTool => {
+  graph.createWorkflow();
+  const tools = graph.agentContexts.get(agentId)?.graphTools as
+    | t.GenericTool[]
+    | undefined;
+  const tool = tools?.find(
+    (candidate) => 'name' in candidate && candidate.name === Constants.SUBAGENT
+  );
+  if (tool == null) {
+    throw new Error(`Expected subagent tool for ${agentId}`);
+  }
+  return tool;
+};
+
+describe('graph factory', () => {
+  it('constructs standard and multi-agent graph adapters', () => {
+    const standard = createGraph({
+      kind: 'standard',
+      input: { runId: 'standard-factory', agents: [makeAgent('standard')] },
+    });
+    const multiAgent = createGraph({
+      kind: 'multi-agent',
+      input: {
+        runId: 'multi-agent-factory',
+        agents: [makeAgent('multi')],
+        edges: [],
+      },
+    });
+
+    expect(standard).toBeInstanceOf(StandardGraph);
+    expect(standard).not.toBeInstanceOf(MultiAgentGraph);
+    expect(multiAgent).toBeInstanceOf(MultiAgentGraph);
+  });
+
+  it('accepts a union-typed graph factory request', () => {
+    const construct = (request: GraphFactoryRequest): StandardGraph =>
+      createGraph(request);
+    const graph = construct({
+      kind: 'standard',
+      input: { runId: 'union-factory', agents: [makeAgent('union')] },
+    });
+
+    expect(graph).toBeInstanceOf(StandardGraph);
+  });
+
+  it('rejects invalid per-member recursion limits', () => {
+    expect(() =>
+      createGraph({
+        kind: 'multi-agent',
+        input: {
+          runId: 'invalid-member-limit',
+          agents: [makeAgent('member')],
+          edges: [],
+          memberRecursionLimit: 0,
+        },
+      })
+    ).toThrow(/memberRecursionLimit must be a positive safe integer/);
+  });
+
+  it('keeps direct StandardGraph construction compatible with agent children', async () => {
+    const parent = {
+      ...makeAgent('parent'),
+      subagentConfigs: [
+        {
+          type: 'worker',
+          name: 'Worker',
+          description: 'Completes one isolated task.',
+          agentInputs: makeAgent('worker'),
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph({
+      runId: 'direct-standard-factory',
+      agents: [parent],
+    });
+    graph.setSubagentModelOverride(
+      createFakeStreamingLLM({ responses: ['worker complete'] })
+    );
+
+    const result = await getSubagentTool(graph, 'parent').invoke(
+      { description: 'Complete the task.', subagent_type: 'worker' },
+      invokeConfig
+    );
+
+    expect(result).toBe('worker complete');
+  });
+
+  it('fails early when direct construction cannot instantiate a graph child', () => {
+    const parent = {
+      ...makeAgent('parent'),
+      subagentConfigs: [
+        {
+          kind: 'graph' as const,
+          type: 'team',
+          name: 'Team',
+          description: 'Runs one member.',
+          agents: [makeAgent('member')],
+          edges: [],
+          entryAgentId: 'member',
+          resultAgentId: 'member',
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph({
+      runId: 'direct-graph-child-factory',
+      agents: [parent],
+    });
+
+    expect(() => graph.createWorkflow()).toThrow(
+      /constructing the parent with createGraph\(\)/
+    );
+  });
+
+  it('propagates an injected factory through child and grandchild graphs', async () => {
+    const requests: GraphFactoryRequest[] = [];
+    const graphFactory: GraphFactory = (request) => {
+      requests.push(request);
+      if (request.kind === 'multi-agent') {
+        return new MultiAgentGraph(request.input, { graphFactory });
+      }
+      return new StandardGraph(request.input, { graphFactory });
+    };
+    const nestedToolCall: ToolCall = {
+      id: 'call_nested_specialist',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'Complete the specialist step.',
+        subagent_type: 'specialist',
+      },
+      type: 'tool_call',
+    };
+    const router = {
+      ...makeAgent('router'),
+      subagentConfigs: [
+        {
+          type: 'specialist',
+          name: 'Specialist',
+          description: 'Completes the nested specialist step.',
+          agentInputs: makeAgent('specialist'),
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const root = {
+      ...makeAgent('root'),
+      maxSubagentDepth: 2,
+      subagentConfigs: [
+        {
+          type: 'router',
+          name: 'Router',
+          description: 'Delegates one nested specialist step.',
+          allowNested: true,
+          agentInputs: router,
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph(
+      { runId: 'recursive-graph-factory', agents: [root] },
+      { graphFactory }
+    );
+    graph.setSubagentModelOverride(
+      createFakeStreamingLLM({
+        responses: ['delegating', 'specialist complete', 'router complete'],
+        toolCalls: [nestedToolCall],
+      })
+    );
+
+    const result = await getSubagentTool(graph, 'root').invoke(
+      { description: 'Route the task.', subagent_type: 'router' },
+      invokeConfig
+    );
+
+    expect(result).toBe('router complete');
+    expect(
+      requests.map(({ kind, input }) => ({
+        kind,
+        agentIds: input.agents.map(({ agentId }) => agentId),
+      }))
+    ).toEqual([
+      { kind: 'standard', agentIds: ['router'] },
+      { kind: 'standard', agentIds: ['specialist'] },
+    ]);
+  });
+});

package/src/graphs/applyGraphRuntimeConfig.ts

@@ -0,0 +1,25 @@
+import type { StandardGraph } from './Graph';
+
+export type GraphRuntimeConfig = Pick<
+  StandardGraph,
+  | 'hookRegistry'
+  | 'humanInTheLoop'
+  | 'toolOutputReferences'
+  | 'eagerEventToolExecution'
+  | 'codeSessionToolNames'
+  | 'interruptingToolNames'
+  | 'toolExecution'
+>;
+
+export function applyGraphRuntimeConfig(
+  graph: StandardGraph,
+  config: GraphRuntimeConfig
+): void {
+  graph.hookRegistry = config.hookRegistry;
+  graph.humanInTheLoop = config.humanInTheLoop;
+  graph.toolOutputReferences = config.toolOutputReferences;
+  graph.eagerEventToolExecution = config.eagerEventToolExecution;
+  graph.codeSessionToolNames = config.codeSessionToolNames;
+  graph.interruptingToolNames = config.interruptingToolNames;
+  graph.toolExecution = config.toolExecution;
+}

package/src/graphs/createGraph.ts

@@ -0,0 +1,32 @@
+import type {
+  GraphFactory,
+  GraphFactoryDependencies,
+  GraphFactoryRequest,
+} from '@/graphs/graphFactory';
+import type { MultiAgentGraphInput, StandardGraphInput } from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { StandardGraph } from '@/graphs/Graph';
+
+const createGraphByKind: GraphFactory = (request) => {
+  if (request.kind === 'multi-agent') {
+    return new MultiAgentGraph(request.input, dependencies);
+  }
+  return new StandardGraph(request.input, dependencies);
+};
+
+const dependencies: GraphFactoryDependencies = {
+  graphFactory: createGraphByKind,
+};
+
+export function createGraph(request: {
+  kind: 'standard';
+  input: StandardGraphInput;
+}): StandardGraph;
+export function createGraph(request: {
+  kind: 'multi-agent';
+  input: MultiAgentGraphInput;
+}): MultiAgentGraph;
+export function createGraph(request: GraphFactoryRequest): StandardGraph;
+export function createGraph(request: GraphFactoryRequest): StandardGraph {
+  return createGraphByKind(request);
+}

package/src/graphs/graphFactory.ts

@@ -0,0 +1,12 @@
+import type { StandardGraph } from './Graph';
+import type * as t from '@/types';
+
+export type GraphFactoryRequest =
+  | { kind: 'standard'; input: t.StandardGraphInput }
+  | { kind: 'multi-agent'; input: t.MultiAgentGraphInput };
+
+export type GraphFactory = (request: GraphFactoryRequest) => StandardGraph;
+
+export type GraphFactoryDependencies = {
+  graphFactory: GraphFactory;
+};

package/src/graphs/index.ts

@@ -1,2 +1,4 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
+export * from './createGraph';
+export type * from './graphFactory';

package/src/run.ts

@@ -18,6 +18,8 @@ import {
 import type { StringPromptValue } from '@langchain/core/prompt_values';
 import type { MessageContentComplex } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import type { StandardGraph } from '@/graphs/Graph';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 import {
@@ -62,12 +64,12 @@ import {
   createCompletionTitleRunnable,
   createTitleRunnable,
 } from '@/utils/title';
+import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { initializeLangfuseTracing } from './instrumentation';
-import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
+import { createGraph } from '@/graphs/createGraph';
 import { resolveMaxSeals } from '@/llm/preempt';
-import { StandardGraph } from '@/graphs/Graph';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { isOpenAILike } from '@/utils/llm';
@@ -346,30 +348,35 @@ export class Run<_T extends t.BaseGraphState> {
       signal = legacySignal;
     }
 
-    const standardGraph = new StandardGraph({
-      signal,
-      runId: this.id,
-      agents: [agentConfig],
-      langfuse: this.langfuse,
-      tokenCounter: this.tokenCounter,
-      indexTokenCountMap: this.indexTokenCountMap,
-      calibrationRatio: this.calibrationRatio,
-      subagentUsageSink: this.subagentUsageSink,
-      preemption: this.preemption,
-      streamLimits: this.streamLimits,
+    const standardGraph = createGraph({
+      kind: 'standard',
+      input: {
+        signal,
+        runId: this.id,
+        agents: [agentConfig],
+        langfuse: this.langfuse,
+        tokenCounter: this.tokenCounter,
+        indexTokenCountMap: this.indexTokenCountMap,
+        calibrationRatio: this.calibrationRatio,
+        subagentUsageSink: this.subagentUsageSink,
+        preemption: this.preemption,
+        streamLimits: this.streamLimits,
+      },
     });
     /** Propagate compile options from graph config */
     standardGraph.compileOptions = this.applyHITLCheckpointerFallback(
       config.compileOptions
     );
     this.hasCheckpointer = standardGraph.compileOptions?.checkpointer != null;
-    standardGraph.hookRegistry = this.hookRegistry;
-    standardGraph.humanInTheLoop = this.humanInTheLoop;
-    standardGraph.toolOutputReferences = this.toolOutputReferences;
-    standardGraph.eagerEventToolExecution = this.eagerEventToolExecution;
-    standardGraph.codeSessionToolNames = this.codeSessionToolNames;
-    standardGraph.interruptingToolNames = this.interruptingToolNames;
-    standardGraph.toolExecution = this.toolExecution;
+    applyGraphRuntimeConfig(standardGraph, {
+      hookRegistry: this.hookRegistry,
+      humanInTheLoop: this.humanInTheLoop,
+      toolOutputReferences: this.toolOutputReferences,
+      eagerEventToolExecution: this.eagerEventToolExecution,
+      codeSessionToolNames: this.codeSessionToolNames,
+      interruptingToolNames: this.interruptingToolNames,
+      toolExecution: this.toolExecution,
+    });
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
   }
@@ -379,30 +386,35 @@ export class Run<_T extends t.BaseGraphState> {
   ): t.CompiledStateWorkflow {
     const { agents, edges, compileOptions } = config;
 
-    const multiAgentGraph = new MultiAgentGraph({
-      runId: this.id,
-      agents,
-      edges,
-      langfuse: this.langfuse,
-      tokenCounter: this.tokenCounter,
-      indexTokenCountMap: this.indexTokenCountMap,
-      calibrationRatio: this.calibrationRatio,
-      subagentUsageSink: this.subagentUsageSink,
-      preemption: this.preemption,
-      streamLimits: this.streamLimits,
+    const multiAgentGraph = createGraph({
+      kind: 'multi-agent',
+      input: {
+        runId: this.id,
+        agents,
+        edges,
+        langfuse: this.langfuse,
+        tokenCounter: this.tokenCounter,
+        indexTokenCountMap: this.indexTokenCountMap,
+        calibrationRatio: this.calibrationRatio,
+        subagentUsageSink: this.subagentUsageSink,
+        preemption: this.preemption,
+        streamLimits: this.streamLimits,
+      },
     });
 
     multiAgentGraph.compileOptions =
       this.applyHITLCheckpointerFallback(compileOptions);
     this.hasCheckpointer = multiAgentGraph.compileOptions?.checkpointer != null;
 
-    multiAgentGraph.hookRegistry = this.hookRegistry;
-    multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
-    multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
-    multiAgentGraph.eagerEventToolExecution = this.eagerEventToolExecution;
-    multiAgentGraph.codeSessionToolNames = this.codeSessionToolNames;
-    multiAgentGraph.interruptingToolNames = this.interruptingToolNames;
-    multiAgentGraph.toolExecution = this.toolExecution;
+    applyGraphRuntimeConfig(multiAgentGraph, {
+      hookRegistry: this.hookRegistry,
+      humanInTheLoop: this.humanInTheLoop,
+      toolOutputReferences: this.toolOutputReferences,
+      eagerEventToolExecution: this.eagerEventToolExecution,
+      codeSessionToolNames: this.codeSessionToolNames,
+      interruptingToolNames: this.interruptingToolNames,
+      toolExecution: this.toolExecution,
+    });
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();
   }

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

@@ -0,0 +1,242 @@
+import { config as dotenvConfig } from 'dotenv';
+
+dotenvConfig(
+  process.env.LIVE_ENV_PATH == null
+    ? undefined
+    : { path: process.env.LIVE_ENV_PATH }
+);
+dotenvConfig();
+
+import { describe, expect, it, jest } from '@jest/globals';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Constants, GraphEvents, Providers } from '@/common';
+import { StandardGraph } from '@/graphs/Graph';
+import { Run } from '@/run';
+
+jest.setTimeout(180_000);
+
+const liveEnabled = process.env.RUN_GRAPH_SUBAGENT_LIVE_TESTS === '1';
+const requestedProvider = process.env.GRAPH_SUBAGENT_LIVE_PROVIDER;
+const describeIfLive = liveEnabled ? describe : describe.skip;
+
+type LiveProviderCase = {
+  label: string;
+  provider: Providers;
+  model: string;
+  apiKey?: string;
+};
+
+const LIVE_PROVIDER_CASES: readonly LiveProviderCase[] = [
+  {
+    label: 'Anthropic Haiku',
+    provider: Providers.ANTHROPIC,
+    model:
+      process.env.ANTHROPIC_GRAPH_SUBAGENT_LIVE_MODEL ?? 'claude-haiku-4-5',
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  },
+  {
+    label: 'OpenAI GPT-4.1 mini',
+    provider: Providers.OPENAI,
+    model: process.env.OPENAI_GRAPH_SUBAGENT_LIVE_MODEL ?? 'gpt-4.1-mini',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+];
+
+const explicitlyRequestedCase =
+  requestedProvider == null || requestedProvider === ''
+    ? undefined
+    : LIVE_PROVIDER_CASES.find(
+      ({ provider }) =>
+        provider.toLowerCase() === requestedProvider.toLowerCase()
+    );
+
+if (
+  liveEnabled &&
+  requestedProvider != null &&
+  requestedProvider !== '' &&
+  explicitlyRequestedCase == null
+) {
+  throw new Error(
+    `Unknown GRAPH_SUBAGENT_LIVE_PROVIDER "${requestedProvider}".`
+  );
+}
+if (
+  liveEnabled &&
+  explicitlyRequestedCase != null &&
+  (explicitlyRequestedCase.apiKey == null ||
+    explicitlyRequestedCase.apiKey === '')
+) {
+  throw new Error(
+    `Missing credentials for GRAPH_SUBAGENT_LIVE_PROVIDER "${requestedProvider}".`
+  );
+}
+if (
+  liveEnabled &&
+  explicitlyRequestedCase == null &&
+  !LIVE_PROVIDER_CASES.some(({ apiKey }) => apiKey != null && apiKey !== '')
+) {
+  throw new Error(
+    'No graph-subagent live-provider credentials are configured.'
+  );
+}
+
+function createLiveAgent(
+  testCase: LiveProviderCase,
+  agentId: string,
+  marker: string
+): t.AgentInputs {
+  return {
+    agentId,
+    provider: testCase.provider,
+    clientOptions: {
+      modelName: testCase.model,
+      apiKey: testCase.apiKey,
+      temperature: 0,
+      maxTokens: 64,
+      streaming: true,
+      streamUsage: true,
+    },
+    instructions: `You are the ${agentId} validation stage. When asked to proceed, reply with exactly ${marker} and no other text.`,
+    maxContextTokens: 8_000,
+  };
+}
+
+function getGraphSubagentTool(run: Run<t.IState>): t.GenericTool {
+  const tools = (run.Graph as StandardGraph).agentContexts.get('parent')
+    ?.graphTools as t.GenericTool[] | undefined;
+  const subagentTool = tools?.find(
+    (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
+  );
+  if (subagentTool == null) {
+    throw new Error('Expected graph subagent tool');
+  }
+  return subagentTool;
+}
+
+describeIfLive('Graph subagent live providers', () => {
+  for (const testCase of LIVE_PROVIDER_CASES) {
+    const providerSelected =
+      requestedProvider == null ||
+      requestedProvider === '' ||
+      requestedProvider.toLowerCase() === testCase.provider.toLowerCase();
+    const itIfAvailable =
+      providerSelected && testCase.apiKey != null && testCase.apiKey !== ''
+        ? it
+        : it.skip;
+
+    itIfAvailable(
+      `${testCase.label} runs a bounded team and returns only its result member`,
+      async () => {
+        const usageEvents: t.SubagentUsageEvent[] = [];
+        const updateEvents: t.SubagentUpdateEvent[] = [];
+        const entry = createLiveAgent(testCase, 'entry', 'ENTRY_MARKER');
+        const worker = createLiveAgent(testCase, 'worker', 'WORKER_MARKER');
+        const resultAgent = createLiveAgent(testCase, 'result', 'FINAL_MARKER');
+        const parent: t.AgentInputs = {
+          ...createLiveAgent(testCase, 'parent', 'PARENT_MARKER'),
+          maxSubagentDepth: 1,
+          subagentConfigs: [
+            {
+              kind: 'graph',
+              type: 'live-team',
+              name: 'Live Team',
+              description: 'Runs a three-member live-provider chain.',
+              maxTurns: 2,
+              agents: [entry, worker, resultAgent],
+              edges: [
+                {
+                  from: 'entry',
+                  to: 'worker',
+                  edgeType: 'direct',
+                  prompt: 'Proceed with the worker validation stage.',
+                },
+                {
+                  from: 'worker',
+                  to: 'result',
+                  edgeType: 'direct',
+                  prompt: 'Proceed with the result validation stage.',
+                },
+              ],
+              entryAgentId: 'entry',
+              resultAgentId: 'result',
+            },
+          ],
+        };
+        const rootRunId = `graph-subagent-live-${testCase.provider}-${Date.now()}`;
+        const run = await Run.create<t.IState>({
+          runId: rootRunId,
+          graphConfig: { type: 'standard', agents: [parent] },
+          returnContent: true,
+          skipCleanup: true,
+          subagentUsageSink: (event) => {
+            usageEvents.push(event);
+          },
+          customHandlers: {
+            [GraphEvents.ON_SUBAGENT_UPDATE]: {
+              handle: (_event, data): void => {
+                updateEvents.push(data as t.SubagentUpdateEvent);
+              },
+            },
+          },
+        });
+        const invokeConfig: RunnableConfig = {
+          configurable: {
+            thread_id: `graph-subagent-live-${testCase.provider}`,
+          },
+        };
+
+        const output = await getGraphSubagentTool(run).invoke(
+          {
+            description: 'Begin the entry validation stage.',
+            subagent_type: 'live-team',
+          },
+          invokeConfig
+        );
+        const outputText = String(output);
+
+        expect(outputText).toContain('FINAL_MARKER');
+        expect(outputText).not.toContain('ENTRY_MARKER');
+        expect(outputText).not.toContain('WORKER_MARKER');
+        expect(usageEvents.map((event) => event.memberAgentId).sort()).toEqual([
+          'entry',
+          'result',
+          'worker',
+        ]);
+        for (const event of usageEvents) {
+          expect(event.runId).toBe(rootRunId);
+          expect(event.parentRunId).toBe(rootRunId);
+          expect(event.depth).toBe(1);
+          expect(event.ancestry?.map((entry) => entry.subagentType)).toEqual([
+            'live-team',
+          ]);
+          expect(event.subagentKind).toBe('graph');
+          expect(event.provider).toBe(testCase.provider);
+          expect(event.model).toBeTruthy();
+          expect(event.usage.total_tokens).toBeGreaterThan(0);
+        }
+        expect(
+          updateEvents.filter((event) => event.phase === 'start')
+        ).toHaveLength(1);
+        expect(
+          updateEvents.filter((event) => event.phase === 'stop')
+        ).toHaveLength(1);
+        for (const event of updateEvents) {
+          expect(event.runId).toBe(rootRunId);
+          expect(event.parentRunId).toBe(rootRunId);
+          expect(event.depth).toBe(1);
+          expect(event.ancestry?.map((entry) => entry.subagentType)).toEqual([
+            'live-team',
+          ]);
+        }
+        expect(
+          new Set(
+            updateEvents
+              .map((event) => event.memberAgentId)
+              .filter((agentId): agentId is string => agentId != null)
+          )
+        ).toEqual(new Set(['entry', 'worker', 'result']));
+      }
+    );
+  }
+});