diff --git a/docs/docs/how_to/chatbots_tools.ipynb b/docs/docs/how_to/chatbots_tools.ipynb index 5ea0c54bbcc..07fff046b30 100644 --- a/docs/docs/how_to/chatbots_tools.ipynb +++ b/docs/docs/how_to/chatbots_tools.ipynb @@ -1,58 +1,37 @@ { "cells": [ - { - "cell_type": "raw", - "metadata": {}, - "source": [ - "---\n", - "sidebar_position: 3\n", - "---" - ] - }, { "cell_type": "markdown", "metadata": {}, "source": [ "# How to add tools to chatbots\n", "\n", - "This section will cover how to create conversational agents: chatbots that can interact with other systems and APIs using tools.\n", + ":::info Prerequisites\n", "\n", - "Before reading this guide, we recommend you read both [the chatbot quickstart](/docs/tutorials/chatbot) in this section and be familiar with [the documentation on agents](/docs/tutorials/agents).\n", + "This guide assumes familiarity with the following concepts:\n", + "\n", + "- [Chatbots](/docs/concepts/#messages)\n", + "- [Agents](/docs/tutorials/agents)\n", + "- [Chat history](/docs/concepts/#chat-history)\n", + "\n", + ":::\n", + "\n", + "This section will cover how to create conversational agents: chatbots that can interact with other systems and APIs using tools.\n", "\n", "## Setup\n", "\n", - "For this guide, we'll be using an [OpenAI tools agent](/docs/how_to/agent_executor) with a single tool for searching the web. The default will be powered by [Tavily](/docs/integrations/tools/tavily_search), but you can switch it out for any similar tool. The rest of this section will assume you're using Tavily.\n", + "For this guide, we'll be using a [tool calling agent](/docs/how_to/agent_executor) with a single tool for searching the web. The default will be powered by [Tavily](/docs/integrations/tools/tavily_search), but you can switch it out for any similar tool. The rest of this section will assume you're using Tavily.\n", "\n", "You'll need to [sign up for an account](https://tavily.com/) on the Tavily website, and install the following packages:" ] }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "\u001b[33mWARNING: You are using pip version 22.0.4; however, version 23.3.2 is available.\n", - "You should consider upgrading via the '/Users/jacoblee/.pyenv/versions/3.10.5/bin/python -m pip install --upgrade pip' command.\u001b[0m\u001b[33m\n", - "\u001b[0mNote: you may need to restart the kernel to use updated packages.\n" - ] - }, - { - "data": { - "text/plain": [ - "True" - ] - }, - "execution_count": 1, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ - "%pip install --upgrade --quiet langchain-openai tavily-python\n", + "%pip install --upgrade --quiet langchain-community langchain-openai tavily-python\n", "\n", "# Set env var OPENAI_API_KEY or load from a .env file:\n", "import dotenv\n", @@ -107,17 +86,17 @@ "metadata": {}, "outputs": [], "source": [ - "from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder\n", + "from langchain_core.prompts import ChatPromptTemplate\n", "\n", - "# Adapted from https://smith.langchain.com/hub/hwchase17/openai-tools-agent\n", + "# Adapted from https://smith.langchain.com/hub/jacob/tool-calling-agent\n", "prompt = ChatPromptTemplate.from_messages(\n", " [\n", " (\n", " \"system\",\n", " \"You are a helpful assistant. You may not need to use tools for every query - the user may just want to chat!\",\n", " ),\n", - " MessagesPlaceholder(variable_name=\"messages\"),\n", - " MessagesPlaceholder(variable_name=\"agent_scratchpad\"),\n", + " (\"placeholder\", \"{messages}\"),\n", + " (\"placeholder\", \"{agent_scratchpad}\"),\n", " ]\n", ")" ] @@ -135,9 +114,9 @@ "metadata": {}, "outputs": [], "source": [ - "from langchain.agents import AgentExecutor, create_openai_tools_agent\n", + "from langchain.agents import AgentExecutor, create_tool_calling_agent\n", "\n", - "agent = create_openai_tools_agent(chat, tools, prompt)\n", + "agent = create_tool_calling_agent(chat, tools, prompt)\n", "\n", "agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)" ] @@ -209,7 +188,9 @@ "Invoking: `tavily_search_results_json` with `{'query': 'current conservation status of the Great Barrier Reef'}`\n", "\n", "\n", - "\u001b[0m\u001b[36;1m\u001b[1;3m[{'url': 'https://www.barrierreef.org/news/blog/this-is-the-critical-decade-for-coral-reef-survival', 'content': \"global coral reef conservation. © 2024 Great Barrier Reef Foundation. Website by bigfish.tv #Related News · 29 January 2024 290m more baby corals to help restore and protect the Great Barrier Reef Great Barrier Reef Foundation Managing Director Anna Marsden says it’s not too late if we act now.The Status of Coral Reefs of the World: 2020 report is the largest analysis of global coral reef health ever undertaken. It found that 14 per cent of the world's coral has been lost since 2009. The report also noted, however, that some of these corals recovered during the 10 years to 2019.\"}]\u001b[0m\u001b[32;1m\u001b[1;3mThe current conservation status of the Great Barrier Reef is a critical concern. According to the Great Barrier Reef Foundation, the Status of Coral Reefs of the World: 2020 report found that 14% of the world's coral has been lost since 2009. However, the report also noted that some of these corals recovered during the 10 years to 2019. For more information, you can visit the following link: [Great Barrier Reef Foundation - Conservation Status](https://www.barrierreef.org/news/blog/this-is-the-critical-decade-for-coral-reef-survival)\u001b[0m\n", + "\u001b[0m\u001b[36;1m\u001b[1;3m[{'url': 'https://www.abc.net.au/news/2022-08-04/great-barrier-reef-report-says-coral-recovering-after-bleaching/101296186', 'content': 'Great Barrier Reef hit with widespread and severe bleaching event\\n\\'Devastating\\': Over 90pc of reefs on Great Barrier Reef suffered bleaching over summer, report reveals\\nTop Stories\\nJailed Russian opposition leader Alexei Navalny is dead, says prison service\\nTaylor Swift puts an Aussie twist on a classic as she packs the MCG for the biggest show of her career — as it happened\\nMelbourne comes alive with Swifties, as even those without tickets turn up to soak in the atmosphere\\nAustralian Border Force investigates after arrival of more than 20 men by boat north of Broome\\nOpenAI launches video model that can instantly create short clips from text prompts\\nAntoinette Lattouf loses bid to force ABC to produce emails calling for her dismissal\\nCategory one cyclone makes landfall in Gulf of Carpentaria off NT-Queensland border\\nWhy the RBA may be forced to cut before the Fed\\nBrisbane records \\'wettest day since 2022\\', as woman dies in floodwaters near Mount Isa\\n$45m Sydney beachside home once owned by late radio star is demolished less than a year after sale\\nAnnabel Sutherland\\'s historic double century puts Australia within reach of Test victory over South Africa\\nAlmighty defensive effort delivers Indigenous victory in NRL All Stars clash\\nLisa Wilkinson feared she would have to sell home to pay legal costs of Bruce Lehrmann\\'s defamation case, court documents reveal\\nSupermarkets as you know them are disappearing from our cities\\nNRL issues Broncos\\' Reynolds, Carrigan with breach notices after public scrap\\nPopular Now\\nJailed Russian opposition leader Alexei Navalny is dead, says prison service\\nTaylor Swift puts an Aussie twist on a classic as she packs the MCG for the biggest show of her career — as it happened\\n$45m Sydney beachside home once owned by late radio star is demolished less than a year after sale\\nAustralian Border Force investigates after arrival of more than 20 men by boat north of Broome\\nDealer sentenced for injecting children as young as 12 with methylamphetamine\\nMelbourne comes alive with Swifties, as even those without tickets turn up to soak in the atmosphere\\nTop Stories\\nJailed Russian opposition leader Alexei Navalny is dead, says prison service\\nTaylor Swift puts an Aussie twist on a classic as she packs the MCG for the biggest show of her career — as it happened\\nMelbourne comes alive with Swifties, as even those without tickets turn up to soak in the atmosphere\\nAustralian Border Force investigates after arrival of more than 20 men by boat north of Broome\\nOpenAI launches video model that can instantly create short clips from text prompts\\nJust In\\nJailed Russian opposition leader Alexei Navalny is dead, says prison service\\nMelbourne comes alive with Swifties, as even those without tickets turn up to soak in the atmosphere\\nTraveller alert after one-year-old in Adelaide reported with measles\\nAntoinette Lattouf loses bid to force ABC to produce emails calling for her dismissal\\nFooter\\nWe acknowledge Aboriginal and Torres Strait Islander peoples as the First Australians and Traditional Custodians of the lands where we live, learn, and work.\\n Increased coral cover could come at a cost\\nThe rapid growth in coral cover appears to have come at the expense of the diversity of coral on the reef, with most of the increases accounted for by fast-growing branching coral called Acropora.\\n Documents obtained by the ABC under Freedom of Information laws revealed the Morrison government had forced AIMS to rush the report\\'s release and orchestrated a \"leak\" of the material to select media outlets ahead of the reef being considered for inclusion on the World Heritage In Danger list.\\n The reef\\'s status and potential inclusion on the In Danger list were due to be discussed at the 45th session of the World Heritage Committee in Russia in June this year, but the meeting was indefinitely postponed due to the war in Ukraine.\\n More from ABC\\nEditorial Policies\\nGreat Barrier Reef coral cover at record levels after mass-bleaching events, report shows\\nGreat Barrier Reef coral cover at record levels after mass-bleaching events, report shows\\nRecord coral cover is being seen across much of the Great Barrier Reef as it recovers from past storms and mass-bleaching events.'}]\u001b[0m\u001b[32;1m\u001b[1;3mThe Great Barrier Reef is currently showing signs of recovery, with record coral cover being seen across much of the reef. This recovery comes after past storms and mass-bleaching events. However, the rapid growth in coral cover appears to have come at the expense of the diversity of coral on the reef, with most of the increases accounted for by fast-growing branching coral called Acropora. There were discussions about the reef's potential inclusion on the World Heritage In Danger list, but the meeting to consider this was indefinitely postponed due to the war in Ukraine.\n", + "\n", + "You can read more about it in this article: [Great Barrier Reef hit with widespread and severe bleaching event](https://www.abc.net.au/news/2022-08-04/great-barrier-reef-report-says-coral-recovering-after-bleaching/101296186)\u001b[0m\n", "\n", "\u001b[1m> Finished chain.\u001b[0m\n" ] @@ -218,7 +199,7 @@ "data": { "text/plain": [ "{'messages': [HumanMessage(content='What is the current conservation status of the Great Barrier Reef?')],\n", - " 'output': \"The current conservation status of the Great Barrier Reef is a critical concern. According to the Great Barrier Reef Foundation, the Status of Coral Reefs of the World: 2020 report found that 14% of the world's coral has been lost since 2009. However, the report also noted that some of these corals recovered during the 10 years to 2019. For more information, you can visit the following link: [Great Barrier Reef Foundation - Conservation Status](https://www.barrierreef.org/news/blog/this-is-the-critical-decade-for-coral-reef-survival)\"}" + " 'output': \"The Great Barrier Reef is currently showing signs of recovery, with record coral cover being seen across much of the reef. This recovery comes after past storms and mass-bleaching events. However, the rapid growth in coral cover appears to have come at the expense of the diversity of coral on the reef, with most of the increases accounted for by fast-growing branching coral called Acropora. There were discussions about the reef's potential inclusion on the World Heritage In Danger list, but the meeting to consider this was indefinitely postponed due to the war in Ukraine.\\n\\nYou can read more about it in this article: [Great Barrier Reef hit with widespread and severe bleaching event](https://www.abc.net.au/news/2022-08-04/great-barrier-reef-report-says-coral-recovering-after-bleaching/101296186)\"}" ] }, "execution_count": 6, @@ -296,7 +277,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "If preferred, you can also wrap the agent executor in a `RunnableWithMessageHistory` class to internally manage history messages. First, we need to slightly modify the prompt to take a separate input variable so that the wrapper can parse which input value to store as history:" + "If preferred, you can also wrap the agent executor in a [`RunnableWithMessageHistory`](/docs/how_to/message_history/) class to internally manage history messages. Let's redeclare it this way:" ] }, { @@ -305,20 +286,7 @@ "metadata": {}, "outputs": [], "source": [ - "# Adapted from https://smith.langchain.com/hub/hwchase17/openai-tools-agent\n", - "prompt = ChatPromptTemplate.from_messages(\n", - " [\n", - " (\n", - " \"system\",\n", - " \"You are a helpful assistant. You may not need to use tools for every query - the user may just want to chat!\",\n", - " ),\n", - " MessagesPlaceholder(variable_name=\"chat_history\"),\n", - " (\"human\", \"{input}\"),\n", - " MessagesPlaceholder(variable_name=\"agent_scratchpad\"),\n", - " ]\n", - ")\n", - "\n", - "agent = create_openai_tools_agent(chat, tools, prompt)\n", + "agent = create_tool_calling_agent(chat, tools, prompt)\n", "\n", "agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)" ] @@ -332,27 +300,7 @@ }, { "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [], - "source": [ - "from langchain_community.chat_message_histories import ChatMessageHistory\n", - "from langchain_core.runnables.history import RunnableWithMessageHistory\n", - "\n", - "demo_ephemeral_chat_history_for_chain = ChatMessageHistory()\n", - "\n", - "conversational_agent_executor = RunnableWithMessageHistory(\n", - " agent_executor,\n", - " lambda session_id: demo_ephemeral_chat_history_for_chain,\n", - " input_messages_key=\"input\",\n", - " output_messages_key=\"output\",\n", - " history_messages_key=\"chat_history\",\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 10, + "execution_count": 11, "metadata": {}, "outputs": [ { @@ -370,28 +318,44 @@ { "data": { "text/plain": [ - "{'input': \"I'm Nemo!\",\n", - " 'chat_history': [],\n", + "{'messages': [HumanMessage(content=\"I'm Nemo!\")],\n", " 'output': \"Hi Nemo! It's great to meet you. How can I assist you today?\"}" ] }, - "execution_count": 10, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ + "from langchain_community.chat_message_histories import ChatMessageHistory\n", + "from langchain_core.runnables.history import RunnableWithMessageHistory\n", + "\n", + "demo_ephemeral_chat_history_for_chain = ChatMessageHistory()\n", + "\n", + "conversational_agent_executor = RunnableWithMessageHistory(\n", + " agent_executor,\n", + " lambda session_id: demo_ephemeral_chat_history_for_chain,\n", + " input_messages_key=\"messages\",\n", + " output_messages_key=\"output\",\n", + ")\n", + "\n", "conversational_agent_executor.invoke(\n", - " {\n", - " \"input\": \"I'm Nemo!\",\n", - " },\n", + " {\"messages\": [HumanMessage(\"I'm Nemo!\")]},\n", " {\"configurable\": {\"session_id\": \"unused\"}},\n", ")" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "And then if we rerun our wrapped agent executor:" + ] + }, { "cell_type": "code", - "execution_count": 11, + "execution_count": null, "metadata": {}, "outputs": [ { @@ -409,9 +373,9 @@ { "data": { "text/plain": [ - "{'input': 'What is my name?',\n", - " 'chat_history': [HumanMessage(content=\"I'm Nemo!\"),\n", - " AIMessage(content=\"Hi Nemo! It's great to meet you. How can I assist you today?\")],\n", + "{'messages': [HumanMessage(content=\"I'm Nemo!\"),\n", + " AIMessage(content=\"Hi Nemo! It's great to meet you. How can I assist you today?\"),\n", + " HumanMessage(content='What is my name?')],\n", " 'output': 'Your name is Nemo! How can I assist you today, Nemo?'}" ] }, @@ -422,9 +386,7 @@ ], "source": [ "conversational_agent_executor.invoke(\n", - " {\n", - " \"input\": \"What is my name?\",\n", - " },\n", + " {\"messages\": [HumanMessage(\"What is my name?\")]},\n", " {\"configurable\": {\"session_id\": \"unused\"}},\n", ")" ] @@ -433,6 +395,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "This [LangSmith trace](https://smith.langchain.com/public/1a9f712a-7918-4661-b3ff-d979bcc2af42/r) shows what's going on under the hood.\n", + "\n", "## Further reading\n", "\n", "Other types agents can also support conversational responses too - for more, check out the [agents section](/docs/tutorials/agents).\n", @@ -457,7 +421,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.1" + "version": "3.10.5" } }, "nbformat": 4,