docs[minor]: Add tool choice how to guide

docs/core_docs/.gitignore

@@ -71,6 +71,8 @@ docs/how_to/tool_results_pass_to_model.md
 docs/how_to/tool_results_pass_to_model.mdx
 docs/how_to/tool_configure.md
 docs/how_to/tool_configure.mdx
+docs/how_to/tool_choice.md
+docs/how_to/tool_choice.mdx
 docs/how_to/tool_calls_multimodal.md
 docs/how_to/tool_calls_multimodal.mdx
 docs/how_to/tool_calling.md

docs/core_docs/docs/how_to/index.mdx

@@ -75,6 +75,7 @@ These are the core building blocks you can use when building applications.
 - [How to: track token usage](/docs/how_to/chat_token_usage_tracking)
 - [How to: stream tool calls](/docs/how_to/tool_streaming)
 - [How to: few shot prompt tool behavior](/docs/how_to/tool_calling#few-shotting-with-tools)
+- [How to: force a specific tool call](/docs/how_to/tool_choice)
 
 ### Messages
 

docs/core_docs/docs/how_to/tool_choice.ipynb

@@ -0,0 +1,197 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# How to force tool calling behavior\n",
+    "\n",
+    "```{=mdx}\n",
+    "\n",
+    ":::info Prerequisites\n",
+    "\n",
+    "This guide assumes familiarity with the following concepts:\n",
+    "- [Chat models](/docs/concepts/#chat-models)\n",
+    "- [LangChain Tools](/docs/concepts/#tools)\n",
+    "- [How to use a model to call tools](/docs/how_to/tool_calling)\n",
+    "\n",
+    ":::\n",
+    "\n",
+    "```\n",
+    "\n",
+    "In order to force our LLM to select a specific tool, we can use the `tool_choice` parameter to ensure certain behavior. First, let's define our model and tools:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import { tool } from '@langchain/core/tools';\n",
+    "import { z } from 'zod';\n",
+    "\n",
+    "const add = tool((input) => {\n",
+    "    return `${input.a + input.b}`\n",
+    "}, {\n",
+    "    name: \"add\",\n",
+    "    description: \"Adds a and b.\",\n",
+    "    schema: z.object({\n",
+    "        a: z.number(),\n",
+    "        b: z.number(),\n",
+    "    })\n",
+    "})\n",
+    "\n",
+    "const multiply = tool((input) => {\n",
+    "    return `${input.a * input.b}`\n",
+    "}, {\n",
+    "    name: \"Multiply\",\n",
+    "    description: \"Multiplies a and b.\",\n",
+    "    schema: z.object({\n",
+    "        a: z.number(),\n",
+    "        b: z.number(),\n",
+    "    })\n",
+    "})\n",
+    "\n",
+    "const tools = [add, multiply]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import { ChatOpenAI } from '@langchain/openai';\n",
+    "\n",
+    "const llm = new ChatOpenAI({\n",
+    "  model: \"gpt-3.5-turbo\",\n",
+    "})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For example, we can force our tool to call the multiply tool by using the following code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[\n",
+      "  {\n",
+      "    \"name\": \"Multiply\",\n",
+      "    \"args\": {\n",
+      "      \"a\": 2,\n",
+      "      \"b\": 4\n",
+      "    },\n",
+      "    \"type\": \"tool_call\",\n",
+      "    \"id\": \"call_d5isFbUkn17Wjr6yEtNz7dDF\"\n",
+      "  }\n",
+      "]\n"
+     ]
+    }
+   ],
+   "source": [
+    "const llmForcedToMultiply = llm.bindTools(tools, {\n",
+    "  tool_choice: \"Multiply\",\n",
+    "})\n",
+    "const result = await llmForcedToMultiply.invoke(\"what is 2 + 4\");\n",
+    "console.log(JSON.stringify(result.tool_calls, null, 2));"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Even if we pass it something that doesn't require multiplcation - it will still call the tool!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also just force our tool to select at least one of our tools by passing in the \"any\" (or \"required\" which is OpenAI specific) keyword to the `tool_choice` parameter."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[\n",
+      "  {\n",
+      "    \"name\": \"add\",\n",
+      "    \"args\": {\n",
+      "      \"a\": 2,\n",
+      "      \"b\": 3\n",
+      "    },\n",
+      "    \"type\": \"tool_call\",\n",
+      "    \"id\": \"call_La72g7Aj0XHG0pfPX6Dwg2vT\"\n",
+      "  }\n",
+      "]\n"
+     ]
+    }
+   ],
+   "source": [
+    "const llmForcedToUseTool = llm.bindTools(tools, {\n",
+    "  tool_choice: \"any\",\n",
+    "})\n",
+    "const result = await llmForcedToUseTool.invoke(\"What day is today?\");\n",
+    "console.log(JSON.stringify(result.tool_calls, null, 2));"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{=mdx}\n",
+    "\n",
+    ":::note\n",
+    "\n",
+    "We've recently standardized the `tool_choice` field to be consistent across all models which support it. The following table shows the different packages and minium versions required to use the new standardized `tool_choice` field:\n",
+    "\n",
+    "| Package Name        | Min Package Version | Min Core Version |\n",
+    "|---------------------|---------------------|------------------|\n",
+    "| `@langchain/aws`    | `0.0.3`             | `0.2.17`         |\n",
+    "| `@langchain/openai` | `0.2.4`             | `0.2.17`         |\n",
+    "| `@langchain/groq`   | `0.0.14`            | `0.2.17`         |\n",
+    "\n",
+    ":::\n",
+    "\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "TypeScript",
+   "language": "typescript",
+   "name": "tslab"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "mode": "typescript",
+    "name": "javascript",
+    "typescript": true
+   },
+   "file_extension": ".ts",
+   "mimetype": "text/typescript",
+   "name": "typescript",
+   "version": "3.7.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}