langchain 0.3.31 → 1.0.0-alpha.2

package/dist/agents/responses.d.cts

@@ -0,0 +1,121 @@
+import { MultipleStructuredOutputsError, StructuredOutputParsingError } from "./errors.cjs";
+import { FunctionDefinition } from "@langchain/core/language_models/base";
+import { InteropZodObject, InteropZodType } from "@langchain/core/utils/types";
+import { AIMessage } from "@langchain/core/messages";
+
+//#region src/agents/responses.d.ts
+
+/**
+ * Information for tracking structured output tool metadata.
+ * This contains all necessary information to handle structured responses generated
+ * via tool calls, including the original schema, its type classification, and the
+ * corresponding tool implementation used by the tools strategy.
+ */
+declare class ToolStrategy<_T = unknown> {
+  readonly schema: Record<string, unknown>;
+  readonly tool: {
+    type: "function";
+    function: FunctionDefinition;
+  };
+  readonly options?: ToolStrategyOptions | undefined;
+  private constructor();
+  get name(): string;
+  static fromSchema<S extends InteropZodObject>(schema: S, options?: {
+    name?: string;
+    description?: string;
+    strict?: boolean;
+  }, outputOptions?: ToolStrategyOptions): ToolStrategy<S extends InteropZodType<infer U> ? U : unknown>;
+  static fromSchema(schema: Record<string, unknown>, options?: {
+    name?: string;
+    description?: string;
+    strict?: boolean;
+  }, outputOptions?: ToolStrategyOptions): ToolStrategy<Record<string, unknown>>;
+  /**
+   * Parse tool arguments according to the schema.
+   *
+   * @throws {StructuredOutputParsingError} if the response is not valid
+   * @param toolArgs - The arguments from the tool call
+   * @returns The parsed response according to the schema type
+   */
+  parse(toolArgs: Record<string, unknown>): Record<string, unknown>;
+}
+declare class ProviderStrategy<T = unknown> {
+  readonly schema: Record<string, unknown>;
+  // @ts-expect-error - _schemaType is used only for type inference
+  private _schemaType?;
+  private constructor();
+  static fromSchema<T>(schema: InteropZodType<T>): ProviderStrategy<T>;
+  static fromSchema(schema: Record<string, unknown>): ProviderStrategy<Record<string, unknown>>;
+  /**
+   * Parse tool arguments according to the schema. If the response is not valid, return undefined.
+   *
+   * @param toolArgs - The arguments from the tool call
+   * @returns The parsed response according to the schema type
+   */
+  parse(response: AIMessage): any;
+}
+type ResponseFormat = ToolStrategy<any> | ProviderStrategy<any>;
+/**
+ * Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.
+ * This function defines the default behavior for the `responseFormat` parameter, which is:
+ *
+ * - if value is a Zod schema, default to structured output via tool calling
+ * - if value is a JSON schema, default to structured output via tool calling
+ * - if value is a custom response format, return it as is
+ * - if value is an array, ensure all array elements are instance of `ToolStrategy`
+ * @param responseFormat
+ * @returns
+ */
+
+/**
+ * Branded type for ToolStrategy arrays that preserves type information
+ */
+interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {
+  _schemaType?: T;
+}
+type ToolStrategyError = StructuredOutputParsingError | MultipleStructuredOutputsError;
+interface ToolStrategyOptions {
+  /**
+   * Handle errors from the structured output tool call. Using tools to generate structured output
+   * can cause errors, e.g. if:
+   * - you provide multiple structured output schemas and the model calls multiple structured output tools
+   * - if the structured output generated by the tool call doesn't match provided schema
+   *
+   * This property allows to handle these errors in different ways:
+   * - `true` - retry the tool call
+   * - `false` - throw an error
+   * - `string` - retry the tool call with the provided message
+   * - `(error: ToolStrategyError) => Promise<string> | string` - retry with the provided message or throw the error
+   */
+  handleError?: boolean | string | ((error: ToolStrategyError) => Promise<string> | string);
+}
+declare function toolStrategy<T extends InteropZodType<any>>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<T extends InteropZodType<infer U> ? U : never>;
+declare function toolStrategy<T extends readonly InteropZodType<any>[]>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<{ [K in keyof T]: T[K] extends InteropZodType<infer U> ? U : never }[number]>;
+declare function toolStrategy(responseFormat: JsonSchemaFormat, options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;
+declare function toolStrategy(responseFormat: JsonSchemaFormat[], options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;
+declare function providerStrategy<T extends InteropZodType<any>>(responseFormat: T): ProviderStrategy<T extends InteropZodType<infer U> ? U : never>;
+declare function providerStrategy(responseFormat: JsonSchemaFormat): ProviderStrategy<Record<string, unknown>>;
+/**
+ * Special type to indicate that no response format is provided.
+ * When this type is used, the structuredResponse property should not be present in the result.
+ */
+type ResponseFormatUndefined = {
+  __responseFormatUndefined: true;
+};
+/**
+ * Type representing a JSON Schema object format.
+ * This is a strict type that excludes ToolStrategy and ProviderStrategy instances.
+ */
+type JsonSchemaFormat = {
+  type: "null" | "boolean" | "object" | "array" | "number" | "string" | "integer";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean;
+  [key: string]: unknown;
+} & {
+  // Brand to ensure this is not a ToolStrategy or ProviderStrategy
+  __brand?: never;
+};
+//#endregion
+export { JsonSchemaFormat, ProviderStrategy, ResponseFormat, ResponseFormatUndefined, ToolStrategy, TypedToolStrategy, providerStrategy, toolStrategy };
+//# sourceMappingURL=responses.d.cts.map

package/dist/agents/responses.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.cts","names":["InteropZodObject","InteropZodType","AIMessage","FunctionDefinition","StructuredOutputParsingError","MultipleStructuredOutputsError","ToolStrategy","Record","ToolStrategyOptions","S","U","ProviderStrategy","T","ResponseFormat","transformResponseFormat","JsonSchemaFormat","ResponseFormatUndefined","TypedToolStrategy","Array","ToolStrategyError","Promise","toolStrategy","K","providerStrategy"],"sources":["../../src/agents/responses.d.ts"],"sourcesContent":["/* eslint-disable no-instanceof/no-instanceof */\nimport { InteropZodObject, InteropZodType } from \"@langchain/core/utils/types\";\nimport { type AIMessage } from \"@langchain/core/messages\";\nimport { type FunctionDefinition } from \"@langchain/core/language_models/base\";\nimport { StructuredOutputParsingError, MultipleStructuredOutputsError } from \"./errors.js\";\n/**\n * Information for tracking structured output tool metadata.\n * This contains all necessary information to handle structured responses generated\n * via tool calls, including the original schema, its type classification, and the\n * corresponding tool implementation used by the tools strategy.\n */\nexport declare class ToolStrategy<_T = unknown> {\n    readonly schema: Record<string, unknown>;\n    readonly tool: {\n        type: \"function\";\n        function: FunctionDefinition;\n    };\n    readonly options?: ToolStrategyOptions | undefined;\n    private constructor();\n    get name(): string;\n    static fromSchema<S extends InteropZodObject>(schema: S, options?: {\n        name?: string;\n        description?: string;\n        strict?: boolean;\n    }, outputOptions?: ToolStrategyOptions): ToolStrategy<S extends InteropZodType<infer U> ? U : unknown>;\n    static fromSchema(schema: Record<string, unknown>, options?: {\n        name?: string;\n        description?: string;\n        strict?: boolean;\n    }, outputOptions?: ToolStrategyOptions): ToolStrategy<Record<string, unknown>>;\n    /**\n     * Parse tool arguments according to the schema.\n     *\n     * @throws {StructuredOutputParsingError} if the response is not valid\n     * @param toolArgs - The arguments from the tool call\n     * @returns The parsed response according to the schema type\n     */\n    parse(toolArgs: Record<string, unknown>): Record<string, unknown>;\n}\nexport declare class ProviderStrategy<T = unknown> {\n    readonly schema: Record<string, unknown>;\n    // @ts-expect-error - _schemaType is used only for type inference\n    private _schemaType?;\n    private constructor();\n    static fromSchema<T>(schema: InteropZodType<T>): ProviderStrategy<T>;\n    static fromSchema(schema: Record<string, unknown>): ProviderStrategy<Record<string, unknown>>;\n    /**\n     * Parse tool arguments according to the schema. If the response is not valid, return undefined.\n     *\n     * @param toolArgs - The arguments from the tool call\n     * @returns The parsed response according to the schema type\n     */\n    parse(response: AIMessage): any;\n}\nexport type ResponseFormat = ToolStrategy<any> | ProviderStrategy<any>;\n/**\n * Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.\n * This function defines the default behavior for the `responseFormat` parameter, which is:\n *\n * - if value is a Zod schema, default to structured output via tool calling\n * - if value is a JSON schema, default to structured output via tool calling\n * - if value is a custom response format, return it as is\n * - if value is an array, ensure all array elements are instance of `ToolStrategy`\n * @param responseFormat\n * @returns\n */\nexport declare function transformResponseFormat(responseFormat?: InteropZodType<any> | InteropZodType<any>[] | JsonSchemaFormat | JsonSchemaFormat[] | ResponseFormat | ToolStrategy<any>[] | ResponseFormatUndefined, options?: ToolStrategyOptions): ResponseFormat[];\n/**\n * Branded type for ToolStrategy arrays that preserves type information\n */\nexport interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {\n    _schemaType?: T;\n}\nexport type ToolStrategyError = StructuredOutputParsingError | MultipleStructuredOutputsError;\nexport interface ToolStrategyOptions {\n    /**\n     * Handle errors from the structured output tool call. Using tools to generate structured output\n     * can cause errors, e.g. if:\n     * - you provide multiple structured output schemas and the model calls multiple structured output tools\n     * - if the structured output generated by the tool call doesn't match provided schema\n     *\n     * This property allows to handle these errors in different ways:\n     * - `true` - retry the tool call\n     * - `false` - throw an error\n     * - `string` - retry the tool call with the provided message\n     * - `(error: ToolStrategyError) => Promise<string> | string` - retry with the provided message or throw the error\n     */\n    handleError?: boolean | string | ((error: ToolStrategyError) => Promise<string> | string);\n}\nexport declare function toolStrategy<T extends InteropZodType<any>>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport declare function toolStrategy<T extends readonly InteropZodType<any>[]>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<{\n    [K in keyof T]: T[K] extends InteropZodType<infer U> ? U : never;\n}[number]>;\nexport declare function toolStrategy(responseFormat: JsonSchemaFormat, options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;\nexport declare function toolStrategy(responseFormat: JsonSchemaFormat[], options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;\nexport declare function providerStrategy<T extends InteropZodType<any>>(responseFormat: T): ProviderStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport declare function providerStrategy(responseFormat: JsonSchemaFormat): ProviderStrategy<Record<string, unknown>>;\n/**\n * Special type to indicate that no response format is provided.\n * When this type is used, the structuredResponse property should not be present in the result.\n */\nexport type ResponseFormatUndefined = {\n    __responseFormatUndefined: true;\n};\n/**\n * Type representing a JSON Schema object format.\n * This is a strict type that excludes ToolStrategy and ProviderStrategy instances.\n */\nexport type JsonSchemaFormat = {\n    type: \"null\" | \"boolean\" | \"object\" | \"array\" | \"number\" | \"string\" | \"integer\";\n    properties?: Record<string, unknown>;\n    required?: string[];\n    additionalProperties?: boolean;\n    [key: string]: unknown;\n} & {\n    // Brand to ensure this is not a ToolStrategy or ProviderStrategy\n    __brand?: never;\n};\n"],"mappings":"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"}

package/dist/agents/responses.d.ts

@@ -0,0 +1,121 @@
+import { MultipleStructuredOutputsError, StructuredOutputParsingError } from "./errors.js";
+import { AIMessage } from "@langchain/core/messages";
+import { InteropZodObject, InteropZodType } from "@langchain/core/utils/types";
+import { FunctionDefinition } from "@langchain/core/language_models/base";
+
+//#region src/agents/responses.d.ts
+
+/**
+ * Information for tracking structured output tool metadata.
+ * This contains all necessary information to handle structured responses generated
+ * via tool calls, including the original schema, its type classification, and the
+ * corresponding tool implementation used by the tools strategy.
+ */
+declare class ToolStrategy<_T = unknown> {
+  readonly schema: Record<string, unknown>;
+  readonly tool: {
+    type: "function";
+    function: FunctionDefinition;
+  };
+  readonly options?: ToolStrategyOptions | undefined;
+  private constructor();
+  get name(): string;
+  static fromSchema<S extends InteropZodObject>(schema: S, options?: {
+    name?: string;
+    description?: string;
+    strict?: boolean;
+  }, outputOptions?: ToolStrategyOptions): ToolStrategy<S extends InteropZodType<infer U> ? U : unknown>;
+  static fromSchema(schema: Record<string, unknown>, options?: {
+    name?: string;
+    description?: string;
+    strict?: boolean;
+  }, outputOptions?: ToolStrategyOptions): ToolStrategy<Record<string, unknown>>;
+  /**
+   * Parse tool arguments according to the schema.
+   *
+   * @throws {StructuredOutputParsingError} if the response is not valid
+   * @param toolArgs - The arguments from the tool call
+   * @returns The parsed response according to the schema type
+   */
+  parse(toolArgs: Record<string, unknown>): Record<string, unknown>;
+}
+declare class ProviderStrategy<T = unknown> {
+  readonly schema: Record<string, unknown>;
+  // @ts-expect-error - _schemaType is used only for type inference
+  private _schemaType?;
+  private constructor();
+  static fromSchema<T>(schema: InteropZodType<T>): ProviderStrategy<T>;
+  static fromSchema(schema: Record<string, unknown>): ProviderStrategy<Record<string, unknown>>;
+  /**
+   * Parse tool arguments according to the schema. If the response is not valid, return undefined.
+   *
+   * @param toolArgs - The arguments from the tool call
+   * @returns The parsed response according to the schema type
+   */
+  parse(response: AIMessage): any;
+}
+type ResponseFormat = ToolStrategy<any> | ProviderStrategy<any>;
+/**
+ * Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.
+ * This function defines the default behavior for the `responseFormat` parameter, which is:
+ *
+ * - if value is a Zod schema, default to structured output via tool calling
+ * - if value is a JSON schema, default to structured output via tool calling
+ * - if value is a custom response format, return it as is
+ * - if value is an array, ensure all array elements are instance of `ToolStrategy`
+ * @param responseFormat
+ * @returns
+ */
+
+/**
+ * Branded type for ToolStrategy arrays that preserves type information
+ */
+interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {
+  _schemaType?: T;
+}
+type ToolStrategyError = StructuredOutputParsingError | MultipleStructuredOutputsError;
+interface ToolStrategyOptions {
+  /**
+   * Handle errors from the structured output tool call. Using tools to generate structured output
+   * can cause errors, e.g. if:
+   * - you provide multiple structured output schemas and the model calls multiple structured output tools
+   * - if the structured output generated by the tool call doesn't match provided schema
+   *
+   * This property allows to handle these errors in different ways:
+   * - `true` - retry the tool call
+   * - `false` - throw an error
+   * - `string` - retry the tool call with the provided message
+   * - `(error: ToolStrategyError) => Promise<string> | string` - retry with the provided message or throw the error
+   */
+  handleError?: boolean | string | ((error: ToolStrategyError) => Promise<string> | string);
+}
+declare function toolStrategy<T extends InteropZodType<any>>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<T extends InteropZodType<infer U> ? U : never>;
+declare function toolStrategy<T extends readonly InteropZodType<any>[]>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<{ [K in keyof T]: T[K] extends InteropZodType<infer U> ? U : never }[number]>;
+declare function toolStrategy(responseFormat: JsonSchemaFormat, options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;
+declare function toolStrategy(responseFormat: JsonSchemaFormat[], options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;
+declare function providerStrategy<T extends InteropZodType<any>>(responseFormat: T): ProviderStrategy<T extends InteropZodType<infer U> ? U : never>;
+declare function providerStrategy(responseFormat: JsonSchemaFormat): ProviderStrategy<Record<string, unknown>>;
+/**
+ * Special type to indicate that no response format is provided.
+ * When this type is used, the structuredResponse property should not be present in the result.
+ */
+type ResponseFormatUndefined = {
+  __responseFormatUndefined: true;
+};
+/**
+ * Type representing a JSON Schema object format.
+ * This is a strict type that excludes ToolStrategy and ProviderStrategy instances.
+ */
+type JsonSchemaFormat = {
+  type: "null" | "boolean" | "object" | "array" | "number" | "string" | "integer";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean;
+  [key: string]: unknown;
+} & {
+  // Brand to ensure this is not a ToolStrategy or ProviderStrategy
+  __brand?: never;
+};
+//#endregion
+export { JsonSchemaFormat, ProviderStrategy, ResponseFormat, ResponseFormatUndefined, ToolStrategy, TypedToolStrategy, providerStrategy, toolStrategy };
+//# sourceMappingURL=responses.d.ts.map

package/dist/agents/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","names":["InteropZodObject","InteropZodType","AIMessage","FunctionDefinition","StructuredOutputParsingError","MultipleStructuredOutputsError","ToolStrategy","Record","ToolStrategyOptions","S","U","ProviderStrategy","T","ResponseFormat","transformResponseFormat","JsonSchemaFormat","ResponseFormatUndefined","TypedToolStrategy","Array","ToolStrategyError","Promise","toolStrategy","K","providerStrategy"],"sources":["../../src/agents/responses.d.ts"],"sourcesContent":["/* eslint-disable no-instanceof/no-instanceof */\nimport { InteropZodObject, InteropZodType } from \"@langchain/core/utils/types\";\nimport { type AIMessage } from \"@langchain/core/messages\";\nimport { type FunctionDefinition } from \"@langchain/core/language_models/base\";\nimport { StructuredOutputParsingError, MultipleStructuredOutputsError } from \"./errors.js\";\n/**\n * Information for tracking structured output tool metadata.\n * This contains all necessary information to handle structured responses generated\n * via tool calls, including the original schema, its type classification, and the\n * corresponding tool implementation used by the tools strategy.\n */\nexport declare class ToolStrategy<_T = unknown> {\n    readonly schema: Record<string, unknown>;\n    readonly tool: {\n        type: \"function\";\n        function: FunctionDefinition;\n    };\n    readonly options?: ToolStrategyOptions | undefined;\n    private constructor();\n    get name(): string;\n    static fromSchema<S extends InteropZodObject>(schema: S, options?: {\n        name?: string;\n        description?: string;\n        strict?: boolean;\n    }, outputOptions?: ToolStrategyOptions): ToolStrategy<S extends InteropZodType<infer U> ? U : unknown>;\n    static fromSchema(schema: Record<string, unknown>, options?: {\n        name?: string;\n        description?: string;\n        strict?: boolean;\n    }, outputOptions?: ToolStrategyOptions): ToolStrategy<Record<string, unknown>>;\n    /**\n     * Parse tool arguments according to the schema.\n     *\n     * @throws {StructuredOutputParsingError} if the response is not valid\n     * @param toolArgs - The arguments from the tool call\n     * @returns The parsed response according to the schema type\n     */\n    parse(toolArgs: Record<string, unknown>): Record<string, unknown>;\n}\nexport declare class ProviderStrategy<T = unknown> {\n    readonly schema: Record<string, unknown>;\n    // @ts-expect-error - _schemaType is used only for type inference\n    private _schemaType?;\n    private constructor();\n    static fromSchema<T>(schema: InteropZodType<T>): ProviderStrategy<T>;\n    static fromSchema(schema: Record<string, unknown>): ProviderStrategy<Record<string, unknown>>;\n    /**\n     * Parse tool arguments according to the schema. If the response is not valid, return undefined.\n     *\n     * @param toolArgs - The arguments from the tool call\n     * @returns The parsed response according to the schema type\n     */\n    parse(response: AIMessage): any;\n}\nexport type ResponseFormat = ToolStrategy<any> | ProviderStrategy<any>;\n/**\n * Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.\n * This function defines the default behavior for the `responseFormat` parameter, which is:\n *\n * - if value is a Zod schema, default to structured output via tool calling\n * - if value is a JSON schema, default to structured output via tool calling\n * - if value is a custom response format, return it as is\n * - if value is an array, ensure all array elements are instance of `ToolStrategy`\n * @param responseFormat\n * @returns\n */\nexport declare function transformResponseFormat(responseFormat?: InteropZodType<any> | InteropZodType<any>[] | JsonSchemaFormat | JsonSchemaFormat[] | ResponseFormat | ToolStrategy<any>[] | ResponseFormatUndefined, options?: ToolStrategyOptions): ResponseFormat[];\n/**\n * Branded type for ToolStrategy arrays that preserves type information\n */\nexport interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {\n    _schemaType?: T;\n}\nexport type ToolStrategyError = StructuredOutputParsingError | MultipleStructuredOutputsError;\nexport interface ToolStrategyOptions {\n    /**\n     * Handle errors from the structured output tool call. Using tools to generate structured output\n     * can cause errors, e.g. if:\n     * - you provide multiple structured output schemas and the model calls multiple structured output tools\n     * - if the structured output generated by the tool call doesn't match provided schema\n     *\n     * This property allows to handle these errors in different ways:\n     * - `true` - retry the tool call\n     * - `false` - throw an error\n     * - `string` - retry the tool call with the provided message\n     * - `(error: ToolStrategyError) => Promise<string> | string` - retry with the provided message or throw the error\n     */\n    handleError?: boolean | string | ((error: ToolStrategyError) => Promise<string> | string);\n}\nexport declare function toolStrategy<T extends InteropZodType<any>>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport declare function toolStrategy<T extends readonly InteropZodType<any>[]>(responseFormat: T, options?: ToolStrategyOptions): TypedToolStrategy<{\n    [K in keyof T]: T[K] extends InteropZodType<infer U> ? U : never;\n}[number]>;\nexport declare function toolStrategy(responseFormat: JsonSchemaFormat, options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;\nexport declare function toolStrategy(responseFormat: JsonSchemaFormat[], options?: ToolStrategyOptions): TypedToolStrategy<Record<string, unknown>>;\nexport declare function providerStrategy<T extends InteropZodType<any>>(responseFormat: T): ProviderStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport declare function providerStrategy(responseFormat: JsonSchemaFormat): ProviderStrategy<Record<string, unknown>>;\n/**\n * Special type to indicate that no response format is provided.\n * When this type is used, the structuredResponse property should not be present in the result.\n */\nexport type ResponseFormatUndefined = {\n    __responseFormatUndefined: true;\n};\n/**\n * Type representing a JSON Schema object format.\n * This is a strict type that excludes ToolStrategy and ProviderStrategy instances.\n */\nexport type JsonSchemaFormat = {\n    type: \"null\" | \"boolean\" | \"object\" | \"array\" | \"number\" | \"string\" | \"integer\";\n    properties?: Record<string, unknown>;\n    required?: string[];\n    additionalProperties?: boolean;\n    [key: string]: unknown;\n} & {\n    // Brand to ensure this is not a ToolStrategy or ProviderStrategy\n    __brand?: never;\n};\n"],"mappings":"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"}

package/dist/agents/responses.js

@@ -0,0 +1,162 @@
+import { StructuredOutputParsingError } from "./errors.js";
+import { isInteropZodObject, isInteropZodSchema } from "@langchain/core/utils/types";
+import { Validator, toJsonSchema } from "@langchain/core/utils/json_schema";
+
+//#region src/agents/responses.ts
+/**
+* This is a global counter for generating unique names for tools.
+*/
+let bindingIdentifier = 0;
+/**
+* Information for tracking structured output tool metadata.
+* This contains all necessary information to handle structured responses generated
+* via tool calls, including the original schema, its type classification, and the
+* corresponding tool implementation used by the tools strategy.
+*/
+var ToolStrategy = class ToolStrategy {
+	constructor(schema, tool, options) {
+		this.schema = schema;
+		this.tool = tool;
+		this.options = options;
+	}
+	get name() {
+		return this.tool.function.name;
+	}
+	static fromSchema(schema, options, outputOptions) {
+		/**
+		* It is required for tools to have a name so we can map the tool call to the correct tool
+		* when parsing the response.
+		*/
+		function getFunctionName(name) {
+			return name ?? options?.name ?? `extract-${++bindingIdentifier}`;
+		}
+		if (isInteropZodSchema(schema)) {
+			const asJsonSchema$1 = toJsonSchema(schema);
+			const tool$1 = {
+				type: "function",
+				function: {
+					name: getFunctionName(),
+					strict: options?.strict,
+					description: options?.description ?? asJsonSchema$1.description ?? "Tool for extracting structured output from the model's response.",
+					parameters: asJsonSchema$1
+				}
+			};
+			return new ToolStrategy(asJsonSchema$1, tool$1, outputOptions);
+		}
+		let functionDefinition;
+		if (typeof schema.name === "string" && typeof schema.parameters === "object" && schema.parameters != null) functionDefinition = schema;
+		else functionDefinition = {
+			name: getFunctionName(schema.title),
+			description: schema.description ?? "",
+			parameters: schema
+		};
+		const asJsonSchema = toJsonSchema(schema);
+		const tool = {
+			type: "function",
+			name: getFunctionName(),
+			function: functionDefinition
+		};
+		return new ToolStrategy(asJsonSchema, tool, outputOptions);
+	}
+	/**
+	* Parse tool arguments according to the schema.
+	*
+	* @throws {StructuredOutputParsingError} if the response is not valid
+	* @param toolArgs - The arguments from the tool call
+	* @returns The parsed response according to the schema type
+	*/
+	parse(toolArgs) {
+		const validator = new Validator(this.schema);
+		const result = validator.validate(toolArgs);
+		if (!result.valid) throw new StructuredOutputParsingError(this.name, result.errors.map((e) => e.error));
+		return toolArgs;
+	}
+};
+var ProviderStrategy = class ProviderStrategy {
+	_schemaType;
+	constructor(schema) {
+		this.schema = schema;
+	}
+	static fromSchema(schema) {
+		const asJsonSchema = toJsonSchema(schema);
+		return new ProviderStrategy(asJsonSchema);
+	}
+	/**
+	* Parse tool arguments according to the schema. If the response is not valid, return undefined.
+	*
+	* @param toolArgs - The arguments from the tool call
+	* @returns The parsed response according to the schema type
+	*/
+	parse(response) {
+		/**
+		* return if the response doesn't contain valid content
+		*/
+		if (typeof response.content !== "string" || response.content === "") return;
+		try {
+			const content = JSON.parse(response.content);
+			const validator = new Validator(this.schema);
+			const result = validator.validate(content);
+			if (!result.valid) return;
+			return content;
+		} catch (error) {}
+	}
+};
+/**
+* Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.
+* This function defines the default behavior for the `responseFormat` parameter, which is:
+*
+* - if value is a Zod schema, default to structured output via tool calling
+* - if value is a JSON schema, default to structured output via tool calling
+* - if value is a custom response format, return it as is
+* - if value is an array, ensure all array elements are instance of `ToolStrategy`
+* @param responseFormat
+* @returns
+*/
+function transformResponseFormat(responseFormat, options) {
+	if (!responseFormat) return [];
+	if (typeof responseFormat === "object" && responseFormat !== null && "__responseFormatUndefined" in responseFormat) return [];
+	/**
+	* If users provide an array, it should only contain raw schemas (Zod or JSON schema),
+	* not ToolStrategy or ProviderStrategy instances.
+	*/
+	if (Array.isArray(responseFormat)) {
+		/**
+		* if every entry is a ToolStrategy or ProviderStrategy instance, return the array as is
+		*/
+		if (responseFormat.every((item) => item instanceof ToolStrategy || item instanceof ProviderStrategy)) return responseFormat;
+		/**
+		* Check if all items are Zod schemas
+		*/
+		if (responseFormat.every((item) => isInteropZodObject(item))) return responseFormat.map((item) => ToolStrategy.fromSchema(item, void 0, options));
+		/**
+		* Check if all items are plain objects (JSON schema)
+		*/
+		if (responseFormat.every((item) => typeof item === "object" && item !== null && !isInteropZodObject(item))) return responseFormat.map((item) => ToolStrategy.fromSchema(item, void 0, options));
+		throw new Error("Invalid response format: list contains mixed types.\nAll items must be either InteropZodObject or plain JSON schema objects.");
+	}
+	if (isInteropZodObject(responseFormat)) return [ToolStrategy.fromSchema(responseFormat, void 0, options)];
+	if (responseFormat instanceof ToolStrategy || responseFormat instanceof ProviderStrategy) return [responseFormat];
+	/**
+	* Handle plain object (JSON schema)
+	*/
+	if (typeof responseFormat === "object" && responseFormat !== null && "properties" in responseFormat) return [ToolStrategy.fromSchema(responseFormat, void 0, options)];
+	throw new Error(`Invalid response format: ${String(responseFormat)}`);
+}
+/**
+* Define how to transform the response format from a tool call.
+*
+* @param responseFormat - The response format to transform
+* @param options - The options to use for the transformation
+* @param options.handleError - Whether to handle errors from the tool call
+* @returns The transformed response format
+*/
+function toolStrategy(responseFormat, options) {
+	return transformResponseFormat(responseFormat, options);
+}
+function providerStrategy(responseFormat) {
+	return ProviderStrategy.fromSchema(responseFormat);
+}
+
+//#endregion
+export { ProviderStrategy, ToolStrategy, providerStrategy, toolStrategy, transformResponseFormat };
+//# sourceMappingURL=responses.js.map

package/dist/agents/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","names":["schema: Record<string, unknown>","tool: {\n      type: \"function\";\n      function: FunctionDefinition;\n    }","options?: ToolStrategyOptions","schema: InteropZodObject | Record<string, unknown>","options?: {\n      name?: string;\n      description?: string;\n      strict?: boolean;\n    }","outputOptions?: ToolStrategyOptions","name?: string","asJsonSchema","tool","functionDefinition: FunctionDefinition","toolArgs: Record<string, unknown>","schema: InteropZodType<T> | Record<string, unknown>","response: AIMessage","responseFormat?:\n    | InteropZodType<any>\n    | InteropZodType<any>[]\n    | JsonSchemaFormat\n    | JsonSchemaFormat[]\n    | ResponseFormat\n    | ToolStrategy<any>[]\n    | ResponseFormatUndefined","responseFormat:\n    | InteropZodType<any>\n    | InteropZodType<any>[]\n    | JsonSchemaFormat\n    | JsonSchemaFormat[]","responseFormat: InteropZodType<any> | JsonSchemaFormat"],"sources":["../../src/agents/responses.ts"],"sourcesContent":["/* eslint-disable no-instanceof/no-instanceof */\nimport {\n  InteropZodObject,\n  isInteropZodSchema,\n  InteropZodType,\n  isInteropZodObject,\n} from \"@langchain/core/utils/types\";\nimport { type AIMessage } from \"@langchain/core/messages\";\nimport { toJsonSchema, Validator } from \"@langchain/core/utils/json_schema\";\nimport { type FunctionDefinition } from \"@langchain/core/language_models/base\";\n\nimport {\n  StructuredOutputParsingError,\n  MultipleStructuredOutputsError,\n} from \"./errors.js\";\n\n/**\n * This is a global counter for generating unique names for tools.\n */\nlet bindingIdentifier = 0;\n\n/**\n * Information for tracking structured output tool metadata.\n * This contains all necessary information to handle structured responses generated\n * via tool calls, including the original schema, its type classification, and the\n * corresponding tool implementation used by the tools strategy.\n */\nexport class ToolStrategy<_T = unknown> {\n  private constructor(\n    /**\n     * The original JSON Schema provided for structured output\n     */\n    public readonly schema: Record<string, unknown>,\n\n    /**\n     * The tool that will be used to parse the tool call arguments.\n     */\n    public readonly tool: {\n      type: \"function\";\n      function: FunctionDefinition;\n    },\n\n    /**\n     * The options to use for the tool output.\n     */\n    public readonly options?: ToolStrategyOptions\n  ) {}\n\n  get name() {\n    return this.tool.function.name;\n  }\n\n  static fromSchema<S extends InteropZodObject>(\n    schema: S,\n    options?: {\n      name?: string;\n      description?: string;\n      strict?: boolean;\n    },\n    outputOptions?: ToolStrategyOptions\n  ): ToolStrategy<S extends InteropZodType<infer U> ? U : unknown>;\n\n  static fromSchema(\n    schema: Record<string, unknown>,\n    options?: {\n      name?: string;\n      description?: string;\n      strict?: boolean;\n    },\n    outputOptions?: ToolStrategyOptions\n  ): ToolStrategy<Record<string, unknown>>;\n\n  static fromSchema(\n    schema: InteropZodObject | Record<string, unknown>,\n    options?: {\n      name?: string;\n      description?: string;\n      strict?: boolean;\n    },\n    outputOptions?: ToolStrategyOptions\n  ): ToolStrategy<any> {\n    /**\n     * It is required for tools to have a name so we can map the tool call to the correct tool\n     * when parsing the response.\n     */\n    function getFunctionName(name?: string) {\n      return name ?? options?.name ?? `extract-${++bindingIdentifier}`;\n    }\n\n    if (isInteropZodSchema(schema)) {\n      const asJsonSchema = toJsonSchema(schema);\n      const tool = {\n        type: \"function\" as const,\n        function: {\n          name: getFunctionName(),\n          strict: options?.strict,\n          description:\n            options?.description ??\n            asJsonSchema.description ??\n            \"Tool for extracting structured output from the model's response.\",\n          parameters: asJsonSchema,\n        },\n      };\n      return new ToolStrategy(asJsonSchema, tool, outputOptions);\n    }\n\n    let functionDefinition: FunctionDefinition;\n    if (\n      typeof schema.name === \"string\" &&\n      typeof schema.parameters === \"object\" &&\n      schema.parameters != null\n    ) {\n      functionDefinition = schema as unknown as FunctionDefinition;\n    } else {\n      functionDefinition = {\n        name: getFunctionName(schema.title as string),\n        description: (schema.description as string) ?? \"\",\n        parameters: schema,\n      };\n    }\n    const asJsonSchema = toJsonSchema(schema);\n    const tool = {\n      type: \"function\" as const,\n      name: getFunctionName(),\n      function: functionDefinition,\n    };\n    return new ToolStrategy(asJsonSchema, tool, outputOptions);\n  }\n\n  /**\n   * Parse tool arguments according to the schema.\n   *\n   * @throws {StructuredOutputParsingError} if the response is not valid\n   * @param toolArgs - The arguments from the tool call\n   * @returns The parsed response according to the schema type\n   */\n  parse(toolArgs: Record<string, unknown>): Record<string, unknown> {\n    const validator = new Validator(this.schema);\n    const result = validator.validate(toolArgs);\n    if (!result.valid) {\n      throw new StructuredOutputParsingError(\n        this.name,\n        result.errors.map((e) => e.error)\n      );\n    }\n    return toolArgs;\n  }\n}\n\nexport class ProviderStrategy<T = unknown> {\n  // @ts-expect-error - _schemaType is used only for type inference\n  private _schemaType?: T;\n\n  private constructor(public readonly schema: Record<string, unknown>) {}\n\n  static fromSchema<T>(schema: InteropZodType<T>): ProviderStrategy<T>;\n\n  static fromSchema(\n    schema: Record<string, unknown>\n  ): ProviderStrategy<Record<string, unknown>>;\n\n  static fromSchema<T = unknown>(\n    schema: InteropZodType<T> | Record<string, unknown>\n  ): ProviderStrategy<T> | ProviderStrategy<Record<string, unknown>> {\n    const asJsonSchema = toJsonSchema(schema);\n    return new ProviderStrategy(asJsonSchema) as\n      | ProviderStrategy<T>\n      | ProviderStrategy<Record<string, unknown>>;\n  }\n\n  /**\n   * Parse tool arguments according to the schema. If the response is not valid, return undefined.\n   *\n   * @param toolArgs - The arguments from the tool call\n   * @returns The parsed response according to the schema type\n   */\n  parse(response: AIMessage) {\n    /**\n     * return if the response doesn't contain valid content\n     */\n    if (typeof response.content !== \"string\" || response.content === \"\") {\n      return;\n    }\n\n    try {\n      const content = JSON.parse(response.content);\n      const validator = new Validator(this.schema);\n      const result = validator.validate(content);\n      if (!result.valid) {\n        return;\n      }\n\n      return content;\n    } catch (error) {\n      // no-op\n    }\n  }\n}\n\nexport type ResponseFormat = ToolStrategy<any> | ProviderStrategy<any>;\n\n/**\n * Handle user input for `responseFormat` parameter of `CreateReactAgentParams`.\n * This function defines the default behavior for the `responseFormat` parameter, which is:\n *\n * - if value is a Zod schema, default to structured output via tool calling\n * - if value is a JSON schema, default to structured output via tool calling\n * - if value is a custom response format, return it as is\n * - if value is an array, ensure all array elements are instance of `ToolStrategy`\n * @param responseFormat\n * @returns\n */\nexport function transformResponseFormat(\n  responseFormat?:\n    | InteropZodType<any>\n    | InteropZodType<any>[]\n    | JsonSchemaFormat\n    | JsonSchemaFormat[]\n    | ResponseFormat\n    | ToolStrategy<any>[]\n    | ResponseFormatUndefined,\n  options?: ToolStrategyOptions\n): ResponseFormat[] {\n  if (!responseFormat) {\n    return [];\n  }\n\n  // Handle ResponseFormatUndefined case\n  if (\n    typeof responseFormat === \"object\" &&\n    responseFormat !== null &&\n    \"__responseFormatUndefined\" in responseFormat\n  ) {\n    return [];\n  }\n\n  /**\n   * If users provide an array, it should only contain raw schemas (Zod or JSON schema),\n   * not ToolStrategy or ProviderStrategy instances.\n   */\n  if (Array.isArray(responseFormat)) {\n    /**\n     * if every entry is a ToolStrategy or ProviderStrategy instance, return the array as is\n     */\n    if (\n      responseFormat.every(\n        (item) =>\n          item instanceof ToolStrategy || item instanceof ProviderStrategy\n      )\n    ) {\n      return responseFormat as unknown as ResponseFormat[];\n    }\n\n    /**\n     * Check if all items are Zod schemas\n     */\n    if (responseFormat.every((item) => isInteropZodObject(item))) {\n      return responseFormat.map((item) =>\n        ToolStrategy.fromSchema(item as InteropZodObject, undefined, options)\n      );\n    }\n\n    /**\n     * Check if all items are plain objects (JSON schema)\n     */\n    if (\n      responseFormat.every(\n        (item) =>\n          typeof item === \"object\" && item !== null && !isInteropZodObject(item)\n      )\n    ) {\n      return responseFormat.map((item) =>\n        ToolStrategy.fromSchema(item as JsonSchemaFormat, undefined, options)\n      );\n    }\n\n    throw new Error(\n      `Invalid response format: list contains mixed types.\\n` +\n        `All items must be either InteropZodObject or plain JSON schema objects.`\n    );\n  }\n\n  if (isInteropZodObject(responseFormat)) {\n    return [ToolStrategy.fromSchema(responseFormat, undefined, options)];\n  }\n\n  if (\n    responseFormat instanceof ToolStrategy ||\n    responseFormat instanceof ProviderStrategy\n  ) {\n    return [responseFormat];\n  }\n\n  /**\n   * Handle plain object (JSON schema)\n   */\n  if (\n    typeof responseFormat === \"object\" &&\n    responseFormat !== null &&\n    \"properties\" in responseFormat\n  ) {\n    return [\n      ToolStrategy.fromSchema(\n        responseFormat as JsonSchemaFormat,\n        undefined,\n        options\n      ),\n    ];\n  }\n\n  throw new Error(`Invalid response format: ${String(responseFormat)}`);\n}\n\n/**\n * Branded type for ToolStrategy arrays that preserves type information\n */\nexport interface TypedToolStrategy<T = unknown>\n  extends Array<ToolStrategy<any>> {\n  _schemaType?: T;\n}\nexport type ToolStrategyError =\n  | StructuredOutputParsingError\n  | MultipleStructuredOutputsError;\nexport interface ToolStrategyOptions {\n  /**\n   * Handle errors from the structured output tool call. Using tools to generate structured output\n   * can cause errors, e.g. if:\n   * - you provide multiple structured output schemas and the model calls multiple structured output tools\n   * - if the structured output generated by the tool call doesn't match provided schema\n   *\n   * This property allows to handle these errors in different ways:\n   * - `true` - retry the tool call\n   * - `false` - throw an error\n   * - `string` - retry the tool call with the provided message\n   * - `(error: ToolStrategyError) => Promise<string> | string` - retry with the provided message or throw the error\n   */\n  handleError?:\n    | boolean\n    | string\n    | ((error: ToolStrategyError) => Promise<string> | string);\n}\n\nexport function toolStrategy<T extends InteropZodType<any>>(\n  responseFormat: T,\n  options?: ToolStrategyOptions\n): TypedToolStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport function toolStrategy<T extends readonly InteropZodType<any>[]>(\n  responseFormat: T,\n  options?: ToolStrategyOptions\n): TypedToolStrategy<\n  { [K in keyof T]: T[K] extends InteropZodType<infer U> ? U : never }[number]\n>;\nexport function toolStrategy(\n  responseFormat: JsonSchemaFormat,\n  options?: ToolStrategyOptions\n): TypedToolStrategy<Record<string, unknown>>;\nexport function toolStrategy(\n  responseFormat: JsonSchemaFormat[],\n  options?: ToolStrategyOptions\n): TypedToolStrategy<Record<string, unknown>>;\n\n/**\n * Define how to transform the response format from a tool call.\n *\n * @param responseFormat - The response format to transform\n * @param options - The options to use for the transformation\n * @param options.handleError - Whether to handle errors from the tool call\n * @returns The transformed response format\n */\nexport function toolStrategy(\n  responseFormat:\n    | InteropZodType<any>\n    | InteropZodType<any>[]\n    | JsonSchemaFormat\n    | JsonSchemaFormat[],\n  options?: ToolStrategyOptions\n): TypedToolStrategy {\n  return transformResponseFormat(responseFormat, options) as TypedToolStrategy;\n}\n\nexport function providerStrategy<T extends InteropZodType<any>>(\n  responseFormat: T\n): ProviderStrategy<T extends InteropZodType<infer U> ? U : never>;\nexport function providerStrategy(\n  responseFormat: JsonSchemaFormat\n): ProviderStrategy<Record<string, unknown>>;\nexport function providerStrategy(\n  responseFormat: InteropZodType<any> | JsonSchemaFormat\n): ProviderStrategy<any> {\n  return ProviderStrategy.fromSchema(\n    responseFormat as any\n  ) as ProviderStrategy<any>;\n}\n\n/**\n * Special type to indicate that no response format is provided.\n * When this type is used, the structuredResponse property should not be present in the result.\n */\nexport type ResponseFormatUndefined = {\n  __responseFormatUndefined: true;\n};\n\n/**\n * Type representing a JSON Schema object format.\n * This is a strict type that excludes ToolStrategy and ProviderStrategy instances.\n */\nexport type JsonSchemaFormat = {\n  type:\n    | \"null\"\n    | \"boolean\"\n    | \"object\"\n    | \"array\"\n    | \"number\"\n    | \"string\"\n    | \"integer\";\n  properties?: Record<string, unknown>;\n  required?: string[];\n  additionalProperties?: boolean;\n  [key: string]: unknown;\n} & {\n  // Brand to ensure this is not a ToolStrategy or ProviderStrategy\n  __brand?: never;\n};\n"],"mappings":"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"}