From d677aa5d8e4c8d45e0e92e949d86b26f27ff3f54 Mon Sep 17 00:00:00 2001 From: Eugene Yurtsev Date: Thu, 3 Oct 2024 14:33:14 -0400 Subject: [PATCH] x --- .../docs/{concepts.mdx => concepts/index.mdx} | 106 ++---------------- docs/docs/concepts/tools.mdx | 96 ++++++++++++++++ docs/sidebars.js | 12 +- 3 files changed, 119 insertions(+), 95 deletions(-) rename docs/docs/{concepts.mdx => concepts/index.mdx} (96%) create mode 100644 docs/docs/concepts/tools.mdx diff --git a/docs/docs/concepts.mdx b/docs/docs/concepts/index.mdx similarity index 96% rename from docs/docs/concepts.mdx rename to docs/docs/concepts/index.mdx index 1efb3e25da7..1b0ee202d67 100644 --- a/docs/docs/concepts.mdx +++ b/docs/docs/concepts/index.mdx @@ -1,9 +1,16 @@ +--- +sidebar_position: 0 +sidebar_class_name: hidden +--- + # Conceptual guide import ThemedImage from '@theme/ThemedImage'; import useBaseUrl from '@docusaurus/useBaseUrl'; -This section contains introductions to key parts of LangChain. +In this section, you'll find explanations of the key concepts, providing a deeper understanding of core principles. + +The conceptual guide will not cover step-by-step instructions or specific implementation details — those are found in the [How-To Guides](/docs/how_to/) and [Tutorials](/docs/tutorials) sections. For detailed reference material, please visit the [API Reference](https://python.langchain.com/api_reference/). ## Architecture @@ -525,102 +532,13 @@ For key-value store implementations, see [this section](/docs/integrations/store ### Tools -Tools are utilities designed to be called by a model: their inputs are designed to be generated by models, and their outputs are designed to be passed back to models. -Tools are needed whenever you want a model to control parts of your code or call out to external APIs. +[What are tools?](/docs/concepts/tools) -A tool consists of: +OR -1. The `name` of the tool. -2. A `description` of what the tool does. -3. A `JSON schema` defining the inputs to the tool. -4. A `function` (and, optionally, an async variant of the function). +[What are tools?](/docs/concepts/tools): Tools are utilities designed to be called by a model: their inputs are designed to be generated by models, and their outputs are designed to be passed back to models. Tools are needed whenever you want a model to control parts of your code or call out to external APIs. -When a tool is bound to a model, the name, description and JSON schema are provided as context to the model. -Given a list of tools and a set of instructions, a model can request to call one or more tools with specific inputs. -Typical usage may look like the following: - -```python -tools = [...] # Define a list of tools -llm_with_tools = llm.bind_tools(tools) -ai_msg = llm_with_tools.invoke("do xyz...") -# -> AIMessage(tool_calls=[ToolCall(...), ...], ...) -``` - -The `AIMessage` returned from the model MAY have `tool_calls` associated with it. -Read [this guide](/docs/concepts/#aimessage) for more information on what the response type may look like. - -Once the chosen tools are invoked, the results can be passed back to the model so that it can complete whatever task -it's performing. -There are generally two different ways to invoke the tool and pass back the response: - -#### Invoke with just the arguments - -When you invoke a tool with just the arguments, you will get back the raw tool output (usually a string). -This generally looks like: - -```python -# You will want to previously check that the LLM returned tool calls -tool_call = ai_msg.tool_calls[0] -# ToolCall(args={...}, id=..., ...) -tool_output = tool.invoke(tool_call["args"]) -tool_message = ToolMessage( - content=tool_output, - tool_call_id=tool_call["id"], - name=tool_call["name"] -) -``` - -Note that the `content` field will generally be passed back to the model. -If you do not want the raw tool response to be passed to the model, but you still want to keep it around, -you can transform the tool output but also pass it as an artifact (read more about [`ToolMessage.artifact` here](/docs/concepts/#toolmessage)) - -```python -... # Same code as above -response_for_llm = transform(response) -tool_message = ToolMessage( - content=response_for_llm, - tool_call_id=tool_call["id"], - name=tool_call["name"], - artifact=tool_output -) -``` - -#### Invoke with `ToolCall` - -The other way to invoke a tool is to call it with the full `ToolCall` that was generated by the model. -When you do this, the tool will return a ToolMessage. -The benefits of this are that you don't have to write the logic yourself to transform the tool output into a ToolMessage. -This generally looks like: - -```python -tool_call = ai_msg.tool_calls[0] -# -> ToolCall(args={...}, id=..., ...) -tool_message = tool.invoke(tool_call) -# -> ToolMessage( -# content="tool result foobar...", -# tool_call_id=..., -# name="tool_name" -# ) -``` - -If you are invoking the tool this way and want to include an [artifact](/docs/concepts/#toolmessage) for the ToolMessage, you will need to have the tool return two things. -Read more about [defining tools that return artifacts here](/docs/how_to/tool_artifacts/). - -#### Best practices - -When designing tools to be used by a model, it is important to keep in mind that: - -- Chat models that have explicit [tool-calling APIs](/docs/concepts/#functiontool-calling) will be better at tool calling than non-fine-tuned models. -- Models will perform better if the tools have well-chosen names, descriptions, and JSON schemas. This another form of prompt engineering. -- Simple, narrowly scoped tools are easier for models to use than complex tools. - -#### Related - -For specifics on how to use tools, see the [tools how-to guides](/docs/how_to/#tools). - -To use a pre-built tool, see the [tool integration docs](/docs/integrations/tools/). - -### Toolkits +## Toolkits Toolkits are collections of tools that are designed to be used together for specific tasks. They have convenient loading methods. diff --git a/docs/docs/concepts/tools.mdx b/docs/docs/concepts/tools.mdx new file mode 100644 index 00000000000..cc417150d3a --- /dev/null +++ b/docs/docs/concepts/tools.mdx @@ -0,0 +1,96 @@ +# Tools + +Tools are utilities designed to be called by a model: their inputs are designed to be generated by models, and their outputs are designed to be passed back to models. +Tools are needed whenever you want a model to control parts of your code or call out to external APIs. + +A tool consists of: + +1. The `name` of the tool. +2. A `description` of what the tool does. +3. A `JSON schema` defining the inputs to the tool. +4. A `function` (and, optionally, an async variant of the function). + +When a tool is bound to a model, the name, description and JSON schema are provided as context to the model. +Given a list of tools and a set of instructions, a model can request to call one or more tools with specific inputs. +Typical usage may look like the following: + +```python +tools = [...] # Define a list of tools +llm_with_tools = llm.bind_tools(tools) +ai_msg = llm_with_tools.invoke("do xyz...") +# -> AIMessage(tool_calls=[ToolCall(...), ...], ...) +``` + +The `AIMessage` returned from the model MAY have `tool_calls` associated with it. +Read [this guide](/docs/concepts/#aimessage) for more information on what the response type may look like. + +Once the chosen tools are invoked, the results can be passed back to the model so that it can complete whatever task +it's performing. +There are generally two different ways to invoke the tool and pass back the response: + +## Invoke with just the arguments + +When you invoke a tool with just the arguments, you will get back the raw tool output (usually a string). +This generally looks like: + +```python +# You will want to previously check that the LLM returned tool calls +tool_call = ai_msg.tool_calls[0] +# ToolCall(args={...}, id=..., ...) +tool_output = tool.invoke(tool_call["args"]) +tool_message = ToolMessage( + content=tool_output, + tool_call_id=tool_call["id"], + name=tool_call["name"] +) +``` + +Note that the `content` field will generally be passed back to the model. +If you do not want the raw tool response to be passed to the model, but you still want to keep it around, +you can transform the tool output but also pass it as an artifact (read more about [`ToolMessage.artifact` here](/docs/concepts/#toolmessage)) + +```python +... # Same code as above +response_for_llm = transform(response) +tool_message = ToolMessage( + content=response_for_llm, + tool_call_id=tool_call["id"], + name=tool_call["name"], + artifact=tool_output +) +``` + +## Invoke with `ToolCall` + +The other way to invoke a tool is to call it with the full `ToolCall` that was generated by the model. +When you do this, the tool will return a ToolMessage. +The benefits of this are that you don't have to write the logic yourself to transform the tool output into a ToolMessage. +This generally looks like: + +```python +tool_call = ai_msg.tool_calls[0] +# -> ToolCall(args={...}, id=..., ...) +tool_message = tool.invoke(tool_call) +# -> ToolMessage( +# content="tool result foobar...", +# tool_call_id=..., +# name="tool_name" +# ) +``` + +If you are invoking the tool this way and want to include an [artifact](/docs/concepts/#toolmessage) for the ToolMessage, you will need to have the tool return two things. +Read more about [defining tools that return artifacts here](/docs/how_to/tool_artifacts/). + +#### Best practices + +When designing tools to be used by a model, it is important to keep in mind that: + +- Chat models that have explicit [tool-calling APIs](/docs/concepts/#functiontool-calling) will be better at tool calling than non-fine-tuned models. +- Models will perform better if the tools have well-chosen names, descriptions, and JSON schemas. This another form of prompt engineering. +- Simple, narrowly scoped tools are easier for models to use than complex tools. + +#### Related + +For specifics on how to use tools, see the [tools how-to guides](/docs/how_to/#tools). + +To use a pre-built tool, see the [tool integration docs](/docs/integrations/tools/). diff --git a/docs/sidebars.js b/docs/sidebars.js index af0dae43d9e..324912a43f6 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -47,7 +47,17 @@ module.exports = { className: 'hidden', }], }, - "concepts", + { + type: "category", + link: {type: 'doc', id: 'concepts/index'}, + label: "Conceptual Guide", + collapsible: false, + items: [{ + type: 'autogenerated', + dirName: 'concepts', + className: 'hidden', + }], + }, { type: "category", label: "Ecosystem",