index.d.ts 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. import { z } from "zod";
  2. import { CallbackManagerForToolRun } from "../callbacks/manager.js";
  3. import { BaseLangChain } from "../language_models/base.js";
  4. import { type RunnableConfig } from "../runnables/config.js";
  5. import type { RunnableFunc } from "../runnables/base.js";
  6. import { ToolCall, ToolMessage } from "../messages/tool.js";
  7. import { ToolInputParsingException } from "./utils.js";
  8. import type { StructuredToolCallInput, ToolInputSchemaBase, ToolReturnType, ResponseFormat, ToolInputSchemaInputType, ToolInputSchemaOutputType, ToolParams, ToolRunnableConfig, StructuredToolInterface, DynamicToolInput, DynamicStructuredToolInput, ZodObjectAny, StringInputToolSchema, ToolInterface, ToolOutputType } from "./types.js";
  9. import { type JSONSchema } from "../utils/json_schema.js";
  10. export type { BaseDynamicToolInput, ContentAndArtifact, DynamicToolInput, DynamicStructuredToolInput, ResponseFormat, StructuredToolCallInput, StructuredToolInterface, StructuredToolParams, ToolInterface, ToolParams, ToolReturnType, ToolRunnableConfig, ToolInputSchemaBase as ToolSchemaBase, } from "./types.js";
  11. export { isLangChainTool, isRunnableToolLike, isStructuredTool, isStructuredToolParams, } from "./types.js";
  12. export { ToolInputParsingException };
  13. /**
  14. * Base class for Tools that accept input of any shape defined by a Zod schema.
  15. */
  16. export declare abstract class StructuredTool<SchemaT extends ToolInputSchemaBase = ToolInputSchemaBase, SchemaOutputT = ToolInputSchemaOutputType<SchemaT>, SchemaInputT = ToolInputSchemaInputType<SchemaT>, ToolOutputT = ToolOutputType> extends BaseLangChain<StructuredToolCallInput<SchemaT, SchemaInputT>, ToolOutputT | ToolMessage> implements StructuredToolInterface<SchemaT, SchemaInputT, ToolOutputT> {
  17. abstract name: string;
  18. abstract description: string;
  19. abstract schema: SchemaT;
  20. /**
  21. * Whether to return the tool's output directly.
  22. *
  23. * Setting this to true means that after the tool is called,
  24. * an agent should stop looping.
  25. */
  26. returnDirect: boolean;
  27. verboseParsingErrors: boolean;
  28. get lc_namespace(): string[];
  29. /**
  30. * The tool response format.
  31. *
  32. * If "content" then the output of the tool is interpreted as the contents of a
  33. * ToolMessage. If "content_and_artifact" then the output is expected to be a
  34. * two-tuple corresponding to the (content, artifact) of a ToolMessage.
  35. *
  36. * @default "content"
  37. */
  38. responseFormat?: ResponseFormat;
  39. constructor(fields?: ToolParams);
  40. protected abstract _call(arg: SchemaOutputT, runManager?: CallbackManagerForToolRun, parentConfig?: ToolRunnableConfig): Promise<ToolOutputT>;
  41. /**
  42. * Invokes the tool with the provided input and configuration.
  43. * @param input The input for the tool.
  44. * @param config Optional configuration for the tool.
  45. * @returns A Promise that resolves with the tool's output.
  46. */
  47. invoke<TInput extends StructuredToolCallInput<SchemaT, SchemaInputT>, TConfig extends ToolRunnableConfig | undefined>(input: TInput, config?: TConfig): Promise<ToolReturnType<TInput, TConfig, ToolOutputT>>;
  48. /**
  49. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  50. *
  51. * Calls the tool with the provided argument, configuration, and tags. It
  52. * parses the input according to the schema, handles any errors, and
  53. * manages callbacks.
  54. * @param arg The input argument for the tool.
  55. * @param configArg Optional configuration or callbacks for the tool.
  56. * @param tags Optional tags for the tool.
  57. * @returns A Promise that resolves with a string.
  58. */
  59. call<TArg extends StructuredToolCallInput<SchemaT, SchemaInputT>, TConfig extends ToolRunnableConfig | undefined>(arg: TArg, configArg?: TConfig,
  60. /** @deprecated */
  61. tags?: string[]): Promise<ToolReturnType<TArg, TConfig, ToolOutputT>>;
  62. }
  63. /**
  64. * Base class for Tools that accept input as a string.
  65. */
  66. export declare abstract class Tool<ToolOutputT = ToolOutputType> extends StructuredTool<StringInputToolSchema, ToolInputSchemaOutputType<StringInputToolSchema>, ToolInputSchemaInputType<StringInputToolSchema>, ToolOutputT> implements ToolInterface<StringInputToolSchema, ToolInputSchemaInputType<StringInputToolSchema>, ToolOutputT> {
  67. schema: z.ZodEffects<z.ZodObject<{
  68. input: z.ZodOptional<z.ZodString>;
  69. }, "strip", z.ZodTypeAny, {
  70. input?: string | undefined;
  71. }, {
  72. input?: string | undefined;
  73. }>, string | undefined, {
  74. input?: string | undefined;
  75. }>;
  76. constructor(fields?: ToolParams);
  77. /**
  78. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  79. *
  80. * Calls the tool with the provided argument and callbacks. It handles
  81. * string inputs specifically.
  82. * @param arg The input argument for the tool, which can be a string, undefined, or an input of the tool's schema.
  83. * @param callbacks Optional callbacks for the tool.
  84. * @returns A Promise that resolves with a string.
  85. */
  86. call<TArg extends string | undefined | z.input<this["schema"]> | ToolCall, TConfig extends ToolRunnableConfig | undefined>(arg: TArg, callbacks?: TConfig): Promise<ToolReturnType<NonNullable<TArg>, TConfig, ToolOutputT>>;
  87. }
  88. /**
  89. * A tool that can be created dynamically from a function, name, and description.
  90. */
  91. export declare class DynamicTool<ToolOutputT = ToolOutputType> extends Tool<ToolOutputT> {
  92. static lc_name(): string;
  93. name: string;
  94. description: string;
  95. func: DynamicToolInput<ToolOutputT>["func"];
  96. constructor(fields: DynamicToolInput<ToolOutputT>);
  97. /**
  98. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  99. */
  100. call<TArg extends string | undefined | z.input<this["schema"]> | ToolCall, TConfig extends ToolRunnableConfig | undefined>(arg: TArg, configArg?: TConfig): Promise<ToolReturnType<NonNullable<TArg>, TConfig, ToolOutputT>>;
  101. /** @ignore */
  102. _call(input: string, // DynamicTool's _call specifically expects a string after schema transformation
  103. runManager?: CallbackManagerForToolRun, parentConfig?: ToolRunnableConfig): Promise<ToolOutputT>;
  104. }
  105. /**
  106. * A tool that can be created dynamically from a function, name, and
  107. * description, designed to work with structured data. It extends the
  108. * StructuredTool class and overrides the _call method to execute the
  109. * provided function when the tool is called.
  110. *
  111. * Schema can be passed as Zod or JSON schema. The tool will not validate
  112. * input if JSON schema is passed.
  113. */
  114. export declare class DynamicStructuredTool<SchemaT extends ToolInputSchemaBase = ToolInputSchemaBase, SchemaOutputT = ToolInputSchemaOutputType<SchemaT>, SchemaInputT = ToolInputSchemaInputType<SchemaT>, ToolOutputT = ToolOutputType> extends StructuredTool<SchemaT, SchemaOutputT, SchemaInputT, ToolOutputT> {
  115. static lc_name(): string;
  116. name: string;
  117. description: string;
  118. func: DynamicStructuredToolInput<SchemaT, SchemaOutputT, ToolOutputT>["func"];
  119. schema: SchemaT;
  120. constructor(fields: DynamicStructuredToolInput<SchemaT, SchemaOutputT, ToolOutputT>);
  121. /**
  122. * @deprecated Use .invoke() instead. Will be removed in 0.3.0.
  123. */
  124. call<TArg extends StructuredToolCallInput<SchemaT, SchemaInputT>, TConfig extends ToolRunnableConfig | undefined>(arg: TArg, configArg?: TConfig,
  125. /** @deprecated */
  126. tags?: string[]): Promise<ToolReturnType<NonNullable<TArg>, TConfig, ToolOutputT>>;
  127. protected _call(arg: Parameters<DynamicStructuredToolInput<SchemaT, SchemaOutputT>["func"]>[0], runManager?: CallbackManagerForToolRun, parentConfig?: RunnableConfig): Promise<ToolOutputT>;
  128. }
  129. /**
  130. * Abstract base class for toolkits in LangChain. Toolkits are collections
  131. * of tools that agents can use. Subclasses must implement the `tools`
  132. * property to provide the specific tools for the toolkit.
  133. */
  134. export declare abstract class BaseToolkit {
  135. abstract tools: StructuredToolInterface[];
  136. getTools(): StructuredToolInterface[];
  137. }
  138. /**
  139. * Parameters for the tool function.
  140. * Schema can be provided as Zod or JSON schema.
  141. * Both schema types will be validated.
  142. * @template {ToolInputSchemaBase} RunInput The input schema for the tool.
  143. */
  144. interface ToolWrapperParams<RunInput extends ToolInputSchemaBase | undefined = ToolInputSchemaBase | undefined> extends ToolParams {
  145. /**
  146. * The name of the tool. If using with an LLM, this
  147. * will be passed as the tool name.
  148. */
  149. name: string;
  150. /**
  151. * The description of the tool.
  152. * @default `${fields.name} tool`
  153. */
  154. description?: string;
  155. /**
  156. * The input schema for the tool. If using an LLM, this
  157. * will be passed as the tool schema to generate arguments
  158. * for.
  159. */
  160. schema?: RunInput;
  161. /**
  162. * The tool response format.
  163. *
  164. * If "content" then the output of the tool is interpreted as the contents of a
  165. * ToolMessage. If "content_and_artifact" then the output is expected to be a
  166. * two-tuple corresponding to the (content, artifact) of a ToolMessage.
  167. *
  168. * @default "content"
  169. */
  170. responseFormat?: ResponseFormat;
  171. /**
  172. * Whether to return the tool's output directly.
  173. *
  174. * Setting this to true means that after the tool is called,
  175. * an agent should stop looping.
  176. */
  177. returnDirect?: boolean;
  178. }
  179. /**
  180. * Creates a new StructuredTool instance with the provided function, name, description, and schema.
  181. *
  182. * Schema can be provided as Zod or JSON schema, and both will be validated.
  183. *
  184. * @function
  185. * @template {ToolInputSchemaBase} SchemaT The input schema for the tool.
  186. * @template {ToolReturnType} ToolOutputT The output type of the tool.
  187. *
  188. * @param {RunnableFunc<z.output<SchemaT>, ToolOutputT>} func - The function to invoke when the tool is called.
  189. * @param {ToolWrapperParams<SchemaT>} fields - An object containing the following properties:
  190. * @param {string} fields.name The name of the tool.
  191. * @param {string | undefined} fields.description The description of the tool. Defaults to either the description on the Zod schema, or `${fields.name} tool`.
  192. * @param {ZodObjectAny | z.ZodString | undefined} fields.schema The Zod schema defining the input for the tool. If undefined, it will default to a Zod string schema.
  193. *
  194. * @returns {DynamicStructuredTool<SchemaT>} A new StructuredTool instance.
  195. */
  196. export declare function tool<SchemaT extends z.ZodString, ToolOutputT = ToolOutputType>(func: RunnableFunc<SchemaT extends z.ZodString ? z.output<SchemaT> : string, ToolOutputT, ToolRunnableConfig>, fields: ToolWrapperParams<SchemaT>): DynamicTool<ToolOutputT>;
  197. export declare function tool<SchemaT extends ZodObjectAny, SchemaOutputT = z.output<SchemaT>, SchemaInputT = z.input<SchemaT>, ToolOutputT = ToolOutputType>(func: RunnableFunc<SchemaOutputT, ToolOutputT, ToolRunnableConfig>, fields: ToolWrapperParams<SchemaT>): DynamicStructuredTool<SchemaT, SchemaOutputT, SchemaInputT, ToolOutputT>;
  198. export declare function tool<SchemaT extends JSONSchema, SchemaOutputT = ToolInputSchemaOutputType<SchemaT>, SchemaInputT = ToolInputSchemaInputType<SchemaT>, ToolOutputT = ToolOutputType>(func: RunnableFunc<Parameters<DynamicStructuredToolInput<SchemaT>["func"]>[0], ToolOutputT, ToolRunnableConfig>, fields: ToolWrapperParams<SchemaT>): DynamicStructuredTool<SchemaT, SchemaOutputT, SchemaInputT, ToolOutputT>;