Skip to content

Commit 5a31cd8

Browse files
bracesprouljacoblee93
bracesproul
and
jacoblee93
authored
core[minor]docs[minor]: new tool wrapper (#5782)
* core[minor]docs[minor]: Add better tool implementation * add support for non string tool returns * fix bug * cr * fix generics for tools * add some tests * cr * revert obj return type changes * fix typo, add doc * anotha doc * fix tools * chore: lint files * remove bindTools generic * cr * add 0.2.7 warnings to all docs which contain * Update docs, nits * Typos --------- Co-authored-by: jacoblee93 <[email protected]>
1 parent c2c20fe commit 5a31cd8

File tree

6 files changed

+289
-87
lines changed

6 files changed

+289
-87
lines changed

‎docs/core_docs/docs/how_to/custom_tools.ipynb

+89-10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "raw",
5+
"id": "04171ad7",
6+
"metadata": {
7+
"vscode": {
8+
"languageId": "raw"
9+
}
10+
},
11+
"source": [
12+
"---\n",
13+
"keywords: [custom tool, custom tools]\n",
14+
"---"
15+
]
16+
},
317
{
418
"cell_type": "markdown",
519
"id": "5436020b",
@@ -16,14 +30,64 @@
1630
"\n",
1731
":::\n",
1832
"\n",
19-
"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",
33+
"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 some ways you can create custom tools.\n",
2034
"\n",
21-
"In this guide, we will walk through how to do define a tool for two functions:\n",
35+
"The biggest difference here is that the first function requires an object with multiple input fields, while the second one only accepts an object with a single field. Some older agents only work with functions that require single inputs, so it's important to understand the distinction."
36+
]
37+
},
38+
{
39+
"cell_type": "markdown",
40+
"id": "f6ec6ee8",
41+
"metadata": {},
42+
"source": [
43+
"## `tool` function\n",
2244
"\n",
23-
"1. A multiplier function that will multiply two numbers by each other\n",
24-
"2. A made up search function that always returns the string \"LangChain\"\n",
45+
":::note\n",
46+
"Only available in `@langchain/core` version 0.2.7 and above.\n",
47+
":::\n",
2548
"\n",
26-
"The biggest difference here is that the first function requires an object with multiple input fields, while the second one only accepts an object with a single field. Some older agents only work with functions that require single inputs, so it's important to understand the distinction."
49+
"\n",
50+
"The [`tool`](https://api.js.langchain.com/classes/langchain_core_tools.tool.html) wrapper function is a convenience method for turning a JavaScript function into a tool. It requires the function itself along with some additional arguments that define your tool. The most important are:\n",
51+
"\n",
52+
"- The tool's `name`, which the LLM will use as context as well as to reference the tool\n",
53+
"- An optional, but recommended `description`, which the LLM will use as context to know when to use the tool\n",
54+
"- A `schema`, which defines the shape of the tool's input\n",
55+
"\n",
56+
"The `tool` function will return an instance of the [`StructuredTool`](https://api.js.langchain.com/classes/langchain_core_tools.StructuredTool.html) class, so it is compatible with all the existing tool calling infrastructure in the LangChain library."
57+
]
58+
},
59+
{
60+
"cell_type": "code",
61+
"execution_count": 1,
62+
"id": "ecc1ce9d",
63+
"metadata": {},
64+
"outputs": [
65+
{
66+
"name": "stdout",
67+
"output_type": "stream",
68+
"text": [
69+
"The sum of 1 and 2 is 3\n"
70+
]
71+
}
72+
],
73+
"source": [
74+
"import { z } from \"zod\";\n",
75+
"import { tool } from \"@langchain/core/tools\";\n",
76+
"\n",
77+
"const adderSchema = z.object({\n",
78+
" a: z.number(),\n",
79+
" b: z.number(),\n",
80+
"});\n",
81+
"const adderTool = tool(async (input): Promise<string> => {\n",
82+
" const sum = input.a + input.b;\n",
83+
" return `The sum of ${input.a} and ${input.b} is ${sum}`;\n",
84+
"}, {\n",
85+
" name: \"adder\",\n",
86+
" description: \"Adds two numbers together\",\n",
87+
" schema: adderSchema,\n",
88+
"});\n",
89+
"\n",
90+
"await adderTool.invoke({ a: 1, b: 2 });"
2791
]
2892
},
2993
{
@@ -33,7 +97,7 @@
3397
"source": [
3498
"## `DynamicStructuredTool`\n",
3599
"\n",
36-
"Newer and more advanced agents can handle more flexible tools that take multiple inputs. You can use the [`DynamicStructuredTool`](https://v02.api.js.langchain.com/classes/langchain_core_tools.DynamicStructuredTool.html) class to declare them. Here's an example - note that tools must always return strings!"
100+
"You can also use the [`DynamicStructuredTool`](https://api.js.langchain.com/classes/langchain_core_tools.DynamicStructuredTool.html) class to declare tools. Here's an example - note that tools must always return strings!"
37101
]
38102
},
39103
{
@@ -112,6 +176,18 @@
112176
"\n",
113177
"await searchTool.invoke(\"foo\");"
114178
]
179+
},
180+
{
181+
"cell_type": "markdown",
182+
"id": "8eceaf09",
183+
"metadata": {},
184+
"source": [
185+
"## Next steps\n",
186+
"\n",
187+
"You've now seen a few ways to create custom tools in LangChain.\n",
188+
"\n",
189+
"Next, you might be interested in learning [how to use a chat model to call tools](/docs/how_to/tool_calling/)."
190+
]
115191
}
116192
],
117193
"metadata": {
@@ -121,12 +197,15 @@
121197
"name": "deno"
122198
},
123199
"language_info": {
200+
"codemirror_mode": {
201+
"mode": "typescript",
202+
"name": "javascript",
203+
"typescript": true
204+
},
124205
"file_extension": ".ts",
125-
"mimetype": "text/x.typescript",
206+
"mimetype": "text/typescript",
126207
"name": "typescript",
127-
"nb_converter": "script",
128-
"pygments_lexer": "typescript",
129-
"version": "5.3.3"
208+
"version": "3.7.2"
130209
},
131210
"vscode": {
132211
"interpreter": {

‎docs/core_docs/docs/how_to/migrate_agent.ipynb

+14-10
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,13 @@
4949
"\n",
5050
"For basic creation and usage of a tool-calling ReAct-style agent, the\n",
5151
"functionality is the same. First, let's define a model and tool(s), then we'll\n",
52-
"use those to create an agent.\n"
52+
"use those to create an agent.\n",
53+
"\n",
54+
":::note\n",
55+
"The `tool` function is available in `@langchain/core` version 0.2.7 and above.\n",
56+
"\n",
57+
"If you are on an older version of core, you should use instantiate and use [`DynamicStructuredTool`](https://api.js.langchain.com/classes/langchain_core_tools.DynamicStructuredTool.html) instead.\n",
58+
":::"
5359
]
5460
},
5561
{
@@ -61,7 +67,7 @@
6167
},
6268
"outputs": [],
6369
"source": [
64-
"import { DynamicStructuredTool } from \"@langchain/core/tools\";\n",
70+
"import { tool } from \"@langchain/core/tools\";\n",
6571
"import { z } from \"zod\";\n",
6672
"import { ChatAnthropic } from \"@langchain/anthropic\";\n",
6773
"\n",
@@ -70,15 +76,14 @@
7076
" temperature: 0,\n",
7177
"});\n",
7278
"\n",
73-
"const magicTool = new DynamicStructuredTool({\n",
79+
"const magicTool = tool(async ({ input }: { input: number }) => {\n",
80+
" return `${input + 2}`;\n",
81+
"}, {\n",
7482
" name: \"magic_function\",\n",
7583
" description: \"Applies a magic function to an input.\",\n",
7684
" schema: z.object({\n",
7785
" input: z.number(),\n",
7886
" }),\n",
79-
" func: async ({ input }: { input: number }) => {\n",
80-
" return `${input + 2}`;\n",
81-
" },\n",
8287
"});\n",
8388
"\n",
8489
"const tools = [magicTool];\n",
@@ -1532,15 +1537,14 @@
15321537
}
15331538
],
15341539
"source": [
1535-
"const badMagicTool = new DynamicStructuredTool({\n",
1540+
"const badMagicTool = tool(async ({ input }) => {\n",
1541+
" return \"Sorry, there was an error. Please try again.\";\n",
1542+
"}, {\n",
15361543
" name: \"magic_function\",\n",
15371544
" description: \"Applies a magic function to an input.\",\n",
15381545
" schema: z.object({\n",
15391546
" input: z.string(),\n",
15401547
" }),\n",
1541-
" func: async ({ input }) => {\n",
1542-
" return \"Sorry, there was an error. Please try again.\";\n",
1543-
" },\n",
15441548
"});\n",
15451549
"\n",
15461550
"const badTools = [badMagicTool];\n",

‎docs/core_docs/docs/how_to/tool_calling.ipynb

+36-44
Original file line numberDiff line numberDiff line change
@@ -87,16 +87,23 @@
8787
"cell_type": "markdown",
8888
"metadata": {},
8989
"source": [
90-
"A number of models implement helper methods that will take care of formatting and binding different function-like objects to the model.\n",
91-
"Let's take a look at how we might take the following Zod function schema and get different models to invoke it:"
90+
"We can use the `.bindTools()` method to handle the conversion from LangChain tool to our model provider's specific format and bind it to the model (i.e., passing it in each time the model is invoked). A number of models implement helper methods that will take care of formatting and binding different function-like objects to the model.\n",
91+
"Let's create a new tool implementing a Zod schema, then bind it to the model:\n",
92+
"\n",
93+
":::note\n",
94+
"The `tool` function is available in `@langchain/core` version 0.2.7 and above.\n",
95+
"\n",
96+
"If you are on an older version of core, you should use instantiate and use [`DynamicStructuredTool`](https://api.js.langchain.com/classes/langchain_core_tools.DynamicStructuredTool.html) instead.\n",
97+
":::"
9298
]
9399
},
94100
{
95101
"cell_type": "code",
96-
"execution_count": 1,
102+
"execution_count": 2,
97103
"metadata": {},
98104
"outputs": [],
99105
"source": [
106+
"import { tool } from \"@langchain/core/tools\";\n",
100107
"import { z } from \"zod\";\n",
101108
"\n",
102109
"/**\n",
@@ -109,43 +116,25 @@
109116
" .describe(\"The type of operation to execute.\"),\n",
110117
" number1: z.number().describe(\"The first number to operate on.\"),\n",
111118
" number2: z.number().describe(\"The second number to operate on.\"),\n",
112-
"});"
113-
]
114-
},
115-
{
116-
"cell_type": "markdown",
117-
"metadata": {},
118-
"source": [
119-
"We can use the `.bindTools()` method to handle the conversion from LangChain tool to our model provider's specific format and bind it to the model (i.e., passing it in each time the model is invoked). Let's create a `DynamicStructuredTool` implementing a tool based on the above schema, then bind it to the model:"
120-
]
121-
},
122-
{
123-
"cell_type": "code",
124-
"execution_count": 2,
125-
"metadata": {},
126-
"outputs": [],
127-
"source": [
128-
"import { ChatOpenAI } from \"@langchain/openai\";\n",
129-
"import { DynamicStructuredTool } from \"@langchain/core/tools\";\n",
119+
"});\n",
130120
"\n",
131-
"const calculatorTool = new DynamicStructuredTool({\n",
121+
"const calculatorTool = tool(async ({ operation, number1, number2 }) => {\n",
122+
" // Functions must return strings\n",
123+
" if (operation === \"add\") {\n",
124+
" return `${number1 + number2}`;\n",
125+
" } else if (operation === \"subtract\") {\n",
126+
" return `${number1 - number2}`;\n",
127+
" } else if (operation === \"multiply\") {\n",
128+
" return `${number1 * number2}`;\n",
129+
" } else if (operation === \"divide\") {\n",
130+
" return `${number1 / number2}`;\n",
131+
" } else {\n",
132+
" throw new Error(\"Invalid operation.\");\n",
133+
" }\n",
134+
"}, {\n",
132135
" name: \"calculator\",\n",
133136
" description: \"Can perform mathematical operations.\",\n",
134137
" schema: calculatorSchema,\n",
135-
" func: async ({ operation, number1, number2 }) => {\n",
136-
" // Functions must return strings\n",
137-
" if (operation === \"add\") {\n",
138-
" return `${number1 + number2}`;\n",
139-
" } else if (operation === \"subtract\") {\n",
140-
" return `${number1 - number2}`;\n",
141-
" } else if (operation === \"multiply\") {\n",
142-
" return `${number1 * number2}`;\n",
143-
" } else if (operation === \"divide\") {\n",
144-
" return `${number1 / number2}`;\n",
145-
" } else {\n",
146-
" throw new Error(\"Invalid operation.\");\n",
147-
" }\n",
148-
" }\n",
149138
"});\n",
150139
"\n",
151140
"const llmWithTools = llm.bindTools([calculatorTool]);"
@@ -169,9 +158,9 @@
169158
"text": [
170159
"[\n",
171160
" {\n",
172-
" name: \"calculator\",\n",
173-
" args: { operation: \"multiply\", number1: 3, number2: 12 },\n",
174-
" id: \"call_Ri9s27J17B224FEHrFGkLdxH\"\n",
161+
" name: 'calculator',\n",
162+
" args: { operation: 'multiply', number1: 3, number2: 12 },\n",
163+
" id: 'call_5KWEQgV40XVoY1rqDhwyDmli'\n",
175164
" }\n",
176165
"]\n"
177166
]
@@ -189,7 +178,7 @@
189178
"source": [
190179
"```{=mdx}\n",
191180
":::tip\n",
192-
"See a LangSmith trace for the above [here](https://smith.langchain.com/public/14e4b50c-c6cf-4c53-b3ef-da550edb6d66/r).\n",
181+
"See a LangSmith trace for the above [here](https://smith.langchain.com/public/b2222205-7da9-4a5a-8efe-6bc62347705d/r).\n",
193182
":::\n",
194183
"```\n",
195184
"\n",
@@ -538,12 +527,15 @@
538527
"name": "deno"
539528
},
540529
"language_info": {
530+
"codemirror_mode": {
531+
"mode": "typescript",
532+
"name": "javascript",
533+
"typescript": true
534+
},
541535
"file_extension": ".ts",
542-
"mimetype": "text/x.typescript",
536+
"mimetype": "text/typescript",
543537
"name": "typescript",
544-
"nb_converter": "script",
545-
"pygments_lexer": "typescript",
546-
"version": "5.3.3"
538+
"version": "3.7.2"
547539
}
548540
},
549541
"nbformat": 4,

‎docs/core_docs/docs/how_to/tool_calls_multimodal.ipynb

+12-7
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,13 @@
2222
"\n",
2323
"To call tools using such models, simply bind tools to them in the [usual way](/docs/how_to/tool_calling), and invoke the model using content blocks of the desired type (e.g., containing image data).\n",
2424
"\n",
25-
"Below, we demonstrate examples using [OpenAI](/docs/integrations/platforms/openai) and [Anthropic](/docs/integrations/platforms/anthropic). We will use the same image and tool in all cases. Let's first select an image, and build a placeholder tool that expects as input the string \"sunny\", \"cloudy\", or \"rainy\". We will ask the models to describe the weather in the image."
25+
"Below, we demonstrate examples using [OpenAI](/docs/integrations/platforms/openai) and [Anthropic](/docs/integrations/platforms/anthropic). We will use the same image and tool in all cases. Let's first select an image, and build a placeholder tool that expects as input the string \"sunny\", \"cloudy\", or \"rainy\". We will ask the models to describe the weather in the image.\n",
26+
"\n",
27+
":::note\n",
28+
"The `tool` function is available in `@langchain/core` version 0.2.7 and above.\n",
29+
"\n",
30+
"If you are on an older version of core, you should use instantiate and use [`DynamicStructuredTool`](https://api.js.langchain.com/classes/langchain_core_tools.DynamicStructuredTool.html) instead.\n",
31+
":::"
2632
]
2733
},
2834
{
@@ -32,21 +38,20 @@
3238
"metadata": {},
3339
"outputs": [],
3440
"source": [
35-
"import { DynamicStructuredTool } from \"@langchain/core/tools\";\n",
41+
"import { tool } from \"@langchain/core/tools\";\n",
3642
"import { z } from \"zod\";\n",
3743
"\n",
3844
"const imageUrl = \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\";\n",
3945
"\n",
40-
"const weatherTool = new DynamicStructuredTool({\n",
46+
"const weatherTool = tool(async ({ weather }) => {\n",
47+
" console.log(weather);\n",
48+
" return weather;\n",
49+
"}, {\n",
4150
" name: \"multiply\",\n",
4251
" description: \"Describe the weather\",\n",
4352
" schema: z.object({\n",
4453
" weather: z.enum([\"sunny\", \"cloudy\", \"rainy\"])\n",
4554
" }),\n",
46-
" func: async ({ weather }) => {\n",
47-
" console.log(weather);\n",
48-
" return weather;\n",
49-
" },\n",
5055
"});"
5156
]
5257
},

0 commit comments

Comments
 (0)