core[minor]docs[minor]: Add better tool implementation

docs/core_docs/docs/how_to/custom_tools.ipynb

@@ -16,7 +16,7 @@
     "\n",
     ":::\n",
     "\n",
-    "When constructing your own agent, you will need to provide it with a list of Tools that it can use. While LangChain includes some prebuilt tools, it can often be more useful to use tools that use custom logic. This guide will walk you through how to use these `Dynamic` tools.\n",
+    "When constructing your own agent, you will need to provide it with a list of Tools that it can use. While LangChain includes some prebuilt tools, it can often be more useful to use tools that use custom logic. This guide will walk you through how to use these tools.\n",
     "\n",
     "In this guide, we will walk through how to do define a tool for two functions:\n",
     "\n",

langchain-core/src/callbacks/base.ts

@@ -197,7 +197,8 @@ abstract class BaseCallbackHandlerMethodsClass {
    * Called at the end of a Tool run, with the tool output and the run ID.
    */
   handleToolEnd?(
-    output: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    output: string | Record<string, any>,
     runId: string,
     parentRunId?: string,
     tags?: string[]

langchain-core/src/callbacks/manager.ts

@@ -488,7 +488,8 @@ export class CallbackManagerForToolRun
     );
   }
 
-  async handleToolEnd(output: string): Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async handleToolEnd(output: string | Record<string, any>): Promise<void> {
     await Promise.all(
       this.handlers.map((handler) =>
         consumeCallback(async () => {

langchain-core/src/language_models/chat_models.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import {
   AIMessage,
   type BaseMessage,
@@ -147,8 +148,13 @@ export abstract class BaseChatModel<
    * specific tool schema.
    * @param kwargs Any additional parameters to bind.
    */
-  bindTools?(
-    tools: (StructuredToolInterface | Record<string, unknown>)[],
+  bindTools?<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends z.ZodObject<any, any, any, any> = z.ZodObject<any, any, any, any>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    RunOutput extends string | Record<string, any> = string
+  >(
+    tools: (StructuredToolInterface<T, RunOutput> | Record<string, unknown>)[],
     kwargs?: Partial<CallOptions>
   ): Runnable<BaseLanguageModelInput, OutputMessageType, CallOptions>;
 

langchain-core/src/messages/base.ts

@@ -53,9 +53,10 @@ export type MessageContentComplex =
   | MessageContentText
   | MessageContentImageUrl
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | (Record<string, any> & { type?: "text" | "image_url" | string })
+  | (Record<string, any> & { type?: "text" | "image_url" | "tool" | string })
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  | (Record<string, any> & { type?: never });
+  | (Record<string, any> & { type?: never })
+  | Record<string, unknown>;
 
 export type MessageContent = string | MessageContentComplex[];
 

langchain-core/src/runnables/tests/runnable_stream_events_v2.test.ts

@@ -24,7 +24,7 @@ import {
   HumanMessage,
   SystemMessage,
 } from "../../messages/index.js";
-import { DynamicStructuredTool, DynamicTool } from "../../tools.js";
+import { DynamicStructuredTool, DynamicTool, tool } from "../../tools.js";
 import { Document } from "../../documents/document.js";
 import { PromptTemplate } from "../../prompts/prompt.js";
 import { GenerationChunk } from "../../outputs.js";
@@ -1823,6 +1823,78 @@ test("Runnable streamEvents method with simple tools", async () => {
   ]);
 });
 
+test("Runnable streamEvents method with tools that return objects", async () => {
+  const adderFunc = (_params: { x: number; y: number }) => {
+    return { sum: 3 };
+  };
+  const parameterlessTool = tool(adderFunc, {
+    name: "parameterless",
+  });
+  const events = [];
+  const eventStream = parameterlessTool.streamEvents({}, { version: "v2" });
+  for await (const event of eventStream) {
+    events.push(event);
+  }
+
+  expect(events).toEqual([
+    {
+      data: { input: {} },
+      event: "on_tool_start",
+      metadata: {},
+      name: "parameterless",
+      run_id: expect.any(String),
+      tags: [],
+    },
+    {
+      data: {
+        output: {
+          sum: 3,
+        },
+      },
+      event: "on_tool_end",
+      metadata: {},
+      name: "parameterless",
+      run_id: expect.any(String),
+      tags: [],
+    },
+  ]);
+
+  const adderTool = tool(adderFunc, {
+    name: "with_parameters",
+    description: "A tool that does nothing",
+    schema: z.object({
+      x: z.number(),
+      y: z.number(),
+    }),
+  });
+  const events2 = [];
+  const eventStream2 = adderTool.streamEvents(
+    { x: 1, y: 2 },
+    { version: "v2" }
+  );
+  for await (const event of eventStream2) {
+    events2.push(event);
+  }
+  expect(events2).toEqual([
+    {
+      data: { input: { x: 1, y: 2 } },
+      event: "on_tool_start",
+      metadata: {},
+      name: "with_parameters",
+      run_id: expect.any(String),
+      tags: [],
+    },
+    {
+      data: { output: { sum: 3 } },
+      event: "on_tool_end",
+      metadata: {},
+      name: "with_parameters",
+      run_id: expect.any(String),
+      tags: [],
+    },
+  ]);
+});
+
 test("Runnable streamEvents method with a retriever", async () => {
   const retriever = new FakeRetriever({
     output: [