nestjs-langchain 2.0.0 → 2.2.0

package/lib/agent.ts

@@ -1,6 +1,7 @@
 import { Inject, Injectable, Logger, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService } from '@nestjs/core';
 import { createAgent, initChatModel } from 'langchain';
+import type { z, ZodType } from 'zod';
 import {
   AGENT_NAME_TOKEN,
   MODULE_OPTIONS_TOKEN,
@@ -11,6 +12,7 @@ import {
   ModelOption,
 } from './interfaces/langchain-module-options.interface.js';
 import { CompletedRun } from './interfaces/completed-run.interface.js';
+import { RunOptions } from './interfaces/run-options.interface.js';
 import {
   ToolDiscoveryService,
   toolErrors,
@@ -18,13 +20,15 @@ import {
 } from './tools/index.js';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { LOG_CONTEXT, messageOf, RunReporter } from './logging/index.js';
-import { summariseRun } from './run/index.js';
-import { AgentRunError } from './errors/index.js';
+import { DEFAULT_RECURSION_LIMIT } from './constants.js';
+import { isRecursionLimit, summariseRun, UsageAside } from './run/index.js';
+import { outputConfig, RunOutput, structuredOutput } from './output/index.js';
+import { AgentRunError, toRunError } from './errors/index.js';
 import {
   agentNotBootstrapped,
   agentPrefix,
-  agentRunFailed,
   duplicateAgentName,
+  invalidRecursionLimit,
   modelNeverReplied,
   modelNotBuilt,
   modelReplyEmpty,
@@ -59,9 +63,6 @@ export class Agent implements OnModuleInit {
   private readonly logger = new Logger();
   private readonly prefix: string;
   private readonly reporter: RunReporter;
-  // Model failures, which only LangChain's callbacks see. Tool calls are
-  // reported by their wrapper and the tool middlewares.
-  private readonly modelErrors: BaseCallbackHandler;
 
   /** @internal Built by `LangChainModule`, never by hand. */
   constructor(
@@ -79,14 +80,6 @@ export class Agent implements OnModuleInit {
       prefix: this.prefix,
       observer: options.observer,
     });
-    this.modelErrors = BaseCallbackHandler.fromMethods({
-      handleLLMError: (error: unknown) => {
-        this.reporter.logError(`the model failed: ${messageOf(error)}`);
-        this.reporter.notify((observer) =>
-          observer.onModelError?.({ agent: agentName, error }),
-        );
-      },
-    });
   }
 
   /**
@@ -97,6 +90,12 @@ export class Agent implements OnModuleInit {
   async onModuleInit() {
     this.assertUniqueName();
 
+    const { recursionLimit } = this.options;
+
+    if (!isRecursionLimit(recursionLimit)) {
+      throw new Error(invalidRecursionLimit(this.prefix, recursionLimit));
+    }
+
     const tools = await this.toolDiscovery.getToolsFromModules(
       this.options.tools ?? [],
       this.reporter,
@@ -106,8 +105,21 @@ export class Agent implements OnModuleInit {
       model: await this.resolveModel(this.options.model),
       tools,
       systemPrompt: this.options.systemPrompt,
-      // The first wraps the next: `toolErrors` sits right around the tool.
-      middleware: [unknownTools(this.reporter), toolErrors(this.reporter)],
+      // The first wraps the next: `toolErrors` sits right around the tool,
+      // `structuredOutput` right around the model.
+      middleware: [
+        unknownTools(
+          this.reporter,
+          tools.map((tool) => tool.name),
+        ),
+        toolErrors(this.reporter),
+        structuredOutput(),
+      ],
+    }).withConfig({
+      // Traces and callbacks tell agents apart; the unnamed one keeps
+      // LangGraph's name. See #235.
+      runName: this.agentName === UNNAMED_AGENT ? undefined : this.agentName,
+      metadata: { agent: this.agentName },
     });
 
     this.logger.log(
@@ -179,21 +191,65 @@ export class Agent implements OnModuleInit {
    * as an `AgentRunError`, the original error in its `cause`.
    *
    * @param input The user's message.
-   * @returns The model's answer, the tools it called and what the run cost.
+   * @param options With `output`, the schema the answer must match; with
+   * `signal`, what aborts the run; with `recursionLimit`, its most steps.
+   * @returns The model's answer, the object `output` parses when given, the
+   * tools it called and what the run cost.
    * @example
    * ```ts
-   * const { output, tools } = await agent.run('What is 6 times 7?');
+   * const { output, tools } = await agent.run('What is 6 times 7?', {
+   *   signal: AbortSignal.timeout(30_000),
+   * });
+   *
+   * const { output: ticket } = await agent.run(email, {
+   *   output: z.object({ category: z.enum(['billing', 'bug', 'other']) }),
+   * });
    * ```
    */
-  async run(input: string): Promise<CompletedRun> {
+  run<S extends ZodType>(
+    input: string,
+    options: RunOptions & { output: S },
+  ): Promise<CompletedRun<z.output<S>>>;
+  run(
+    input: string,
+    options?: RunOptions & { output?: undefined },
+  ): Promise<CompletedRun>;
+  // Options typed `RunOptions`, whose schema is not known statically. See #280.
+  run(input: string, options?: RunOptions): Promise<CompletedRun<unknown>>;
+  async run(
+    input: string,
+    options?: RunOptions,
+  ): Promise<CompletedRun<unknown>> {
     const startedAt = Date.now();
     const durationMs = () => Date.now() - startedAt;
+    // Always passed: left out, a run from another agent's tool would take
+    // that run's limit. See #315.
+    const recursionLimit =
+      options?.recursionLimit ??
+      this.options.recursionLimit ??
+      DEFAULT_RECURSION_LIMIT;
 
     try {
-      const { answer, messages } = await this.complete(input);
+      // Read in the `try`, and `null` from untyped JavaScript taken as no
+      // options, as LangChain takes a `null` config. See #291.
+      const schema = options?.output;
+
+      if (!isRecursionLimit(recursionLimit)) {
+        throw new AgentRunError(
+          invalidRecursionLimit(this.prefix, recursionLimit),
+          this.agentName,
+        );
+      }
+
+      const output = schema && new RunOutput(schema, this.agentName);
+      const aside = new UsageAside();
+      const { answer, messages } = await this.complete(input, output, aside, {
+        signal: options?.signal,
+        recursionLimit,
+      });
       const finished = {
         durationMs: durationMs(),
-        ...summariseRun(messages),
+        ...summariseRun(messages, output?.toolName, aside.usage),
       };
 
       this.reporter.notify((observer) =>
@@ -202,14 +258,12 @@ export class Agent implements OnModuleInit {
 
       return { status: 'completed', output: answer, ...finished };
     } catch (thrown) {
-      const error =
-        thrown instanceof AgentRunError
-          ? thrown
-          : new AgentRunError(
-              agentRunFailed(this.prefix, thrown),
-              this.agentName,
-              { cause: thrown },
-            );
+      const error = toRunError(thrown, {
+        agent: this.agentName,
+        prefix: this.prefix,
+        signal: options?.signal,
+        recursionLimit,
+      });
 
       this.reporter.notify((observer) =>
         observer.onRunError?.({
@@ -223,9 +277,30 @@ export class Agent implements OnModuleInit {
     }
   }
 
+  // Model failures, which only LangChain's callbacks see; tool calls are
+  // reported by their wrapper and the tool middlewares. One handler per run:
+  // a call the run's signal cuts short is no failure. See #318.
+  private modelErrors(signal: AbortSignal | undefined): BaseCallbackHandler {
+    return BaseCallbackHandler.fromMethods({
+      handleLLMError: (error: unknown) => {
+        if (signal?.aborted) {
+          return;
+        }
+
+        this.reporter.logError(`the model failed: ${messageOf(error)}`);
+        this.reporter.notify((observer) =>
+          observer.onModelError?.({ agent: this.agentName, error }),
+        );
+      },
+    });
+  }
+
   private async complete(
     input: string,
-  ): Promise<{ answer: string; messages: AgentState['messages'] }> {
+    output: RunOutput | undefined,
+    aside: UsageAside,
+    run: Pick<RunOptions, 'signal' | 'recursionLimit'>,
+  ): Promise<{ answer: unknown; messages: AgentState['messages'] }> {
     if (!this.#graph) {
       throw new AgentRunError(
         agentNotBootstrapped(this.prefix),
@@ -233,10 +308,18 @@ export class Agent implements OnModuleInit {
       );
     }
 
-    const { messages }: AgentState = await this.#graph.invoke(
+    const state: AgentState = await this.#graph.invoke(
       { messages: [{ role: 'user', content: input }] },
-      { callbacks: [this.modelErrors, ...(this.options.callbacks ?? [])] },
+      {
+        callbacks: [
+          this.modelErrors(run.signal),
+          ...(this.options.callbacks ?? []),
+        ],
+        configurable: { ...outputConfig(output), ...aside.config },
+        ...run,
+      },
     );
+    const { messages } = state;
 
     const last = messages[messages.length - 1];
 
@@ -247,6 +330,10 @@ export class Agent implements OnModuleInit {
       );
     }
 
+    if (output) {
+      return { answer: output.read(state.structuredResponse), messages };
+    }
+
     // `text`, not `content`: block answers are an array.
     if (!last.text) {
       throw new AgentRunError(modelReplyEmpty(this.prefix), this.agentName);

package/lib/constants.ts

@@ -5,6 +5,30 @@ export const TOOL_PARAMS_METADATA = 'nestjs-langchain:tool-params';
 // Emitted by `emitDecoratorMetadata` on every decorated method.
 export const PARAM_TYPES_METADATA = 'design:paramtypes';
 
+// The agent routes a call with this prefix to structured output, never to the
+// tool. Restated: LangChain does not export it. See #213.
+export const STRUCTURED_OUTPUT_PREFIX = 'extract-';
+
+// Ours rather than LangChain's counter or the schema's title: the same tool on
+// every run, under the prefix no `@Tool` can take. See #281.
+/**
+ * The name of the tool a run with an `output` schema answers through: a test
+ * faking the model queues a call to it.
+ *
+ * @example
+ * ```ts
+ * const model = fakeModel().respondWithTools([
+ *   { name: OUTPUT_TOOL, args: { category: 'bug' } },
+ * ]);
+ *
+ * const { output } = await agent.run(email, { output: Ticket });
+ * ```
+ */
+export const OUTPUT_TOOL = `${STRUCTURED_OUTPUT_PREFIX}output` as const;
+
+// LangChain's default, restated: it does not export it.
+export const DEFAULT_RECURSION_LIMIT = 25;
+
 // The keys `@Module()` writes, restated: `@nestjs/common/constants` is
 // internal. See #97.
 export const MODULE_METADATA_KEYS = [

package/lib/errors/agent-aborted.error.ts

@@ -0,0 +1,22 @@
+import { AgentRunError } from './agent-run.error.js';
+
+/**
+ * The run's `signal` was aborted. Its `reason` is in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await agent.run(question, { signal: AbortSignal.timeout(30_000) });
+ * } catch (error) {
+ *   if (error instanceof AgentAbortedError) {
+ *     console.warn('gave up:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class AgentAbortedError extends AgentRunError {
+  constructor(message: string, agent: string, options?: { cause?: unknown }) {
+    super(message, agent, options);
+    this.name = 'AgentAbortedError';
+  }
+}

package/lib/errors/agent-recursion-limit.error.ts

@@ -0,0 +1,24 @@
+import { AgentRunError } from './agent-run.error.js';
+
+/**
+ * The run took its `recursionLimit` of steps without an answer: the model kept
+ * calling tools. LangGraph's error is in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await agent.run(question, { recursionLimit: 10 });
+ * } catch (error) {
+ *   if (error instanceof AgentRecursionLimitError) {
+ *     return 'This question needs too many steps.';
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class AgentRecursionLimitError extends AgentRunError {
+  constructor(message: string, agent: string, options?: { cause?: unknown }) {
+    super(message, agent, options);
+    this.name = 'AgentRecursionLimitError';
+  }
+}

package/lib/errors/index.ts

@@ -1,2 +1,7 @@
+export { AgentAbortedError } from './agent-aborted.error.js';
+export { AgentRecursionLimitError } from './agent-recursion-limit.error.js';
 export { AgentRunError } from './agent-run.error.js';
+export { toRunError } from './run-error.util.js';
+export { StructuredOutputError } from './structured-output.error.js';
 export { ToolConfigurationError } from './tool-configuration.error.js';
+export { unwrapMiddlewareError } from './unwrap-middleware-error.util.js';

package/lib/errors/messages.ts

@@ -96,14 +96,17 @@ export const schemaContradictsSignature = (
   `${where}: the schema for "${param}" describes ${declared.join(' | ')} ` +
   `but the signature declares ${expected}.`;
 
+// The advice of both messages on a schema with no JSON Schema form.
+const jsonSchemaAdvice =
+  'Declare a schema JSON Schema can express and convert it with .transform(), ' +
+  'such as z.iso.date() or z.iso.datetime() for a date.';
+
 export const noJsonSchemaForm = (
   where: string,
   param: string,
   reason: string,
 ): string =>
-  `${where}: "${param}" has no JSON Schema form (${reason}). ` +
-  'Declare a schema JSON Schema can express and convert it with .transform(), ' +
-  'such as z.iso.datetime() for a date.';
+  `${where}: "${param}" has no JSON Schema form (${reason}). ${jsonSchemaAdvice}`;
 
 export const duplicateParamName = (
   where: string,
@@ -155,4 +158,53 @@ export const modelNeverReplied = (
 export const modelReplyEmpty = (prefix: string): string =>
   `The ${prefix}agent's model replied with no text content.`;
 
+export const runAborted = (prefix: string): string =>
+  `The ${prefix}agent's run was aborted.`;
+
+export const recursionLimitReached = (prefix: string, limit: number): string =>
+  `The ${prefix}agent's run reached its recursion limit of ${limit} steps ` +
+  'without an answer. Raise `recursionLimit`, or check what makes the model ' +
+  'keep calling tools.';
+
+export const invalidRecursionLimit = (prefix: string, limit: unknown): string =>
+  `The ${prefix}agent's \`recursionLimit\` must be an integer of at least 1, ` +
+  `not ${typeof limit === 'string' ? `"${limit}"` : String(limit)}.`;
+
+export const noOutputJsonSchemaForm = (
+  prefix: string,
+  reason: string,
+): string =>
+  `The ${prefix}agent's \`output\` schema has no JSON Schema form (${reason}). ` +
+  jsonSchemaAdvice;
+
+export const outputNotAnObject = (prefix: string): string =>
+  `The ${prefix}agent's \`output\` schema is not an object with named fields: ` +
+  "the model fills it in as a tool's parameters. Wrap it, such as " +
+  '`z.object({ items: z.array(...) })`.';
+
+export const structuredOutputMissing = (prefix: string): string =>
+  `The ${prefix}agent's model replied without the requested structured output.`;
+
+export const structuredOutputInvalid = (
+  prefix: string,
+  reason: string,
+): string =>
+  `The ${prefix}agent's model replied with an output that does not match ` +
+  `the schema: ${reason}`;
+
+export const structuredOutputMultiple = (
+  prefix: string,
+  count: number,
+): string =>
+  `The ${prefix}agent's model replied with ${count} outputs instead of one.`;
+
 export const unknownTool = (): string => 'not a tool of this agent';
+
+// LangChain's answer to a tool the agent does not have, restated:
+// `getInvalidToolError` is not exported. See #264.
+export const invalidTool = (tool: string, tools: string[]): string =>
+  `Error: ${tool} is not a valid tool, try one of [${tools.join(', ')}].`;
+
+export const toolNotRun = (tool: string): string =>
+  `Error: '${tool}' was not run: it came with the final answer. ` +
+  'Call it on its own first if it is needed.';

package/lib/errors/run-error.util.ts

@@ -0,0 +1,57 @@
+import { AgentAbortedError } from './agent-aborted.error.js';
+import { AgentRecursionLimitError } from './agent-recursion-limit.error.js';
+import { AgentRunError } from './agent-run.error.js';
+import {
+  agentRunFailed,
+  recursionLimitReached,
+  runAborted,
+} from './messages.js';
+import { unwrapMiddlewareError } from './unwrap-middleware-error.util.js';
+
+interface FailedRun {
+  agent: string;
+  /** Empty for the unnamed agent, `'MATH '` otherwise. */
+  prefix: string;
+  signal?: AbortSignal;
+  /** The limit the run was given. */
+  recursionLimit: number;
+}
+
+/**
+ * The `AgentRunError` `run()` throws for what the agent's graph threw.
+ *
+ * @internal
+ * @param thrown What the graph threw.
+ * @param run The run that failed.
+ * @returns The error itself when it is one already, else the subclass of its
+ * kind, the original in `cause`.
+ */
+export const toRunError = (
+  thrown: unknown,
+  { agent, prefix, signal, recursionLimit }: FailedRun,
+): AgentRunError => {
+  const cause = unwrapMiddlewareError(thrown);
+
+  if (cause instanceof AgentRunError) {
+    return cause;
+  }
+
+  // The reason itself, which LangChain may have wrapped on its way out.
+  if (signal?.aborted) {
+    return new AgentAbortedError(runAborted(prefix), agent, {
+      cause: signal.reason,
+    });
+  }
+
+  // By name, as LangGraph tells its errors apart; it is not a dependency of
+  // ours. See #194.
+  if (cause instanceof Error && cause.name === 'GraphRecursionError') {
+    return new AgentRecursionLimitError(
+      recursionLimitReached(prefix, recursionLimit),
+      agent,
+      { cause },
+    );
+  }
+
+  return new AgentRunError(agentRunFailed(prefix, cause), agent, { cause });
+};

package/lib/errors/structured-output.error.ts

@@ -0,0 +1,23 @@
+import { AgentRunError } from './agent-run.error.js';
+
+/**
+ * The model's answer to a run with an `output` schema never came, or does not
+ * match the schema. LangChain's or Zod's error, if any, is in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const { output } = await agent.run(ticket, { output: Classification });
+ * } catch (error) {
+ *   if (error instanceof StructuredOutputError) {
+ *     console.error(error.message, error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class StructuredOutputError extends AgentRunError {
+  constructor(message: string, agent: string, options?: { cause?: unknown }) {
+    super(message, agent, options);
+    this.name = 'StructuredOutputError';
+  }
+}

package/lib/errors/unwrap-middleware-error.util.ts

@@ -0,0 +1,19 @@
+import { MiddlewareError } from 'langchain';
+
+/**
+ * The error as thrown, without the `MiddlewareError` LangChain wraps it in at
+ * each `wrapModelCall` middleware it crosses, a provider error included.
+ *
+ * @internal
+ * @param error What the agent's graph threw.
+ * @returns The innermost error.
+ */
+export const unwrapMiddlewareError = (error: unknown): unknown => {
+  let unwrapped = error;
+
+  while (MiddlewareError.isInstance(unwrapped) && unwrapped.cause) {
+    unwrapped = unwrapped.cause;
+  }
+
+  return unwrapped;
+};

package/lib/index.ts

@@ -3,7 +3,14 @@
 export { LangChainModule } from './langchain.module.js';
 export { getAgentToken } from './langchain.module-definition.js';
 export { Agent } from './agent.js';
-export { AgentRunError, ToolConfigurationError } from './errors/index.js';
+export { OUTPUT_TOOL } from './constants.js';
+export {
+  AgentAbortedError,
+  AgentRecursionLimitError,
+  AgentRunError,
+  StructuredOutputError,
+  ToolConfigurationError,
+} from './errors/index.js';
 export { InjectAgent, Tool, ToolParam } from './decorators/index.js';
 export type { ToolOptions, ToolParamOptions } from './decorators/index.js';
 export type {
@@ -16,6 +23,7 @@ export type {
   ToolStartEvent,
 } from './interfaces/agent-observer.interface.js';
 export type { CompletedRun } from './interfaces/completed-run.interface.js';
+export type { RunOptions } from './interfaces/run-options.interface.js';
 export type {
   AgentCallback,
   LangChainModuleOptions,

package/lib/interfaces/completed-run.interface.ts

@@ -7,7 +7,7 @@ import type { RunSummary } from '../run/index.js';
 export interface CompletedRun<TOutput = string> extends RunSummary {
   /** Always `'completed'`: a run that fails throws instead. */
   status: 'completed';
-  /** The model's text answer. */
+  /** The model's text answer, or the object the run's `output` schema parsed. */
   output: TOutput;
   /** How long the run took. */
   durationMs: number;

package/lib/interfaces/langchain-module-options.interface.ts

@@ -73,6 +73,12 @@ export interface LangChainModuleOptions {
   observer?: AgentObserver;
   /** LangChain-native run callbacks, for handlers written against its API. */
   callbacks?: AgentCallback[];
+  /**
+   * The most steps a run may take, each model call and each round of tool
+   * calls counting as one: LangGraph's 25 when omitted. A run's own
+   * `recursionLimit` overrides it.
+   */
+  recursionLimit?: number;
 }
 
 /**

package/lib/interfaces/run-options.interface.ts

@@ -0,0 +1,34 @@
+import type { ZodType } from 'zod';
+
+/**
+ * The options of one run. Passed inline, they type `output` from the schema;
+ * typed `RunOptions`, `output` is `unknown`.
+ *
+ * @example
+ * ```ts
+ * const { output } = await agent.run(email, { output: Ticket }); // a Ticket
+ * await agent.run(question, { signal: AbortSignal.timeout(30_000) });
+ *
+ * const ask = (question: string, options?: RunOptions) =>
+ *   agent.run(question, options); // `output` is unknown
+ * ```
+ */
+export interface RunOptions {
+  /**
+   * The schema the answer must match. `output` is then the object it parses,
+   * typed from it, instead of the model's text.
+   */
+  output?: ZodType;
+  /**
+   * Aborts the run: `run()` throws an `AgentAbortedError`, the signal's
+   * `reason` in `cause`. A tool already running ends in the background, its
+   * result dropped.
+   */
+  signal?: AbortSignal;
+  /**
+   * The most steps the run may take, each model call and each round of tool
+   * calls counting as one, instead of the agent's `recursionLimit`. Past it,
+   * `run()` throws an `AgentRecursionLimitError`.
+   */
+  recursionLimit?: number;
+}

package/lib/output/index.ts

@@ -0,0 +1,5 @@
+export { RunOutput } from './run-output.js';
+export {
+  outputConfig,
+  structuredOutput,
+} from './structured-output.middleware.js';