From 087a4bd2b826849507cd64acbba8e584182ab441 Mon Sep 17 00:00:00 2001 From: Harrison Chase Date: Wed, 3 May 2023 22:44:01 -0700 Subject: [PATCH] improve agent documentation (#4062) --- docs/modules/agents.rst | 37 ++++++++++++++++++--- docs/use_cases/personal_assistants.md | 47 ++++++++++++++++++++------- 2 files changed, 68 insertions(+), 16 deletions(-) diff --git a/docs/modules/agents.rst b/docs/modules/agents.rst index 20592ceb..e90a671d 100644 --- a/docs/modules/agents.rst +++ b/docs/modules/agents.rst @@ -10,6 +10,30 @@ but potentially an unknown chain that depends on the user's input. In these types of chains, there is a “agent” which has access to a suite of tools. Depending on the user input, the agent can then decide which, if any, of these tools to call. +High level pseudocode of agents looks something like: + +- Some user input is received +- The `agent` decides which `tool` - if any - to use, and what the input to that tool should be +- That `tool` is then called with that `tool input`, and an `observation` is recorded (this is just the output of calling that tool with that tool input. +- That history of `tool`, `tool input`, and `observation` is passed back into the `agent`, and it decides what steps to take next +- This is repeated until the `agent` decides it no longer needs to use a `tool`, and then it responds directly to the user. + +The different abstractions involved in agents are as follows: + +- Agent: this is where the logic of the application lives. Agents expose an interface that takes in user input along with a list of previous steps the agent has taken, and returns either an `AgentAction` or `AgentFinish` + - `AgentAction` corresponds to the tool to use and the input to that tool + - `AgentFinish` means the agent is done, and has information around what to return to the user +- Tools: these are the actions an agent can take. What tools you give an agent highly depend on what you want the agent to do +- Toolkits: these are groups of tools designed for a specific use case. For example, in order for an agent to interact with a SQL database in the best way it may need access to one tool to execute queries and another tool to inspect tables. +- Agent Executor: this wraps an agent and a list of tools. This is responsible for the loop of running the agent iteratively until the stopping criteria is met. + +The most important abstraction of the four above to understand is that of the agent. +Although an agent can be defined in whatever way one chooses, the typical way to construct an agent is with: + +- PromptTemplate: this is responsible for taking the user input and previous steps and constructing a prompt to send to the language model +- Language Model: this takes the prompt constructed by the PromptTemplate and returns some output +- Output Parser: this takes the output of the Language Model and parses it into an `AgentAction` or `AgentFinish` object. + In this section of documentation, we first start with a Getting Started notebook to cover how to use all things related to agents in an end-to-end manner. .. toctree:: @@ -23,22 +47,27 @@ We then split the documentation into the following sections: **Tools** -An overview of the various tools LangChain supports. +In this section we cover the different types of tools LangChain supports natively. +We then cover how to add your own tools. **Agents** -An overview of the different agent types. +In this section we cover the different types of agents LangChain supports natively. +We then cover how to modify and create your own agents. **Toolkits** -An overview of toolkits, and examples of the different ones LangChain supports. +In this section we go over the various toolkits that LangChain supports out of the box, +and how to create an agent from them. **Agent Executor** -An overview of the Agent Executor class and examples of how to use it. +In this section we go over the Agent Executor class, which is responsible for calling +the agent and tools in a loop. We go over different ways to customize this, and options you +can use for more control. Go Deeper --------- diff --git a/docs/use_cases/personal_assistants.md b/docs/use_cases/personal_assistants.md index 7ca2975c..9d949ff5 100644 --- a/docs/use_cases/personal_assistants.md +++ b/docs/use_cases/personal_assistants.md @@ -1,23 +1,46 @@ -# Personal Assistants (Agents) +# Agents > [Conceptual Guide](https://docs.langchain.com/docs/use-cases/personal-assistants) -We use "personal assistant" here in a very broad sense. -Personal assistants have a few characteristics: +Agents can be used for a variety of tasks. +Agents combine the decision making ability of a language model with tools in order to create a system +that can execute and implement solutions on your behalf. Before reading any more, it is highly +recommended that you read the documentation in the `agent` module to understand the concepts associated with agents more. +Specifically, you should be familiar with what the `agent`, `tool`, and `agent executor` abstractions are before reading more. -- They can interact with the outside world -- They have knowledge of your data -- They remember your interactions +- [Agent Documentation](../modules/agents.rst) (for interacting with the outside world) -Really all of the functionality in LangChain is relevant for building a personal assistant. -Highlighting specific parts: +## Create Your Own Agent -- [Agent Documentation](../modules/agents.rst) (for interacting with the outside world) -- [Index Documentation](../modules/indexes.rst) (for giving them knowledge of your data) -- [Memory](../modules/memory.rst) (for helping them remember interactions) +Once you have read that documentation, you should be prepared to create your own agent. +What exactly does that involve? +Here's how we recommend getting started with creating your own agent: + +### Step 1: Create Tools + +Agents are largely defined by the tools they can use. +If you have a specific task you want the agent to accomplish, you have to give it access to the right tools. +We have many tools natively in LangChain, so you should first look to see if any of them meet your needs. +But we also make it easy to define a custom tool, so if you need custom tools you should absolutely do that. + +### (Optional) Step 2: Modify Agent + +The built-in LangChain agent types are designed to work well in generic situations, +but you may be able to improve performance by modifying the agent implementation. +There are several ways you could do this: + +1. Modify the base prompt. This can be used to give the agent more context on how it should behave, etc. +2. Modify the output parser. This is necessary if the agent is having trouble parsing the language model output. + +### (Optional) Step 3: Modify Agent Executor + +This step is usually not necessary, as this is pretty general logic. +Possible reasons you would want to modify this include adding different stopping conditions, or handling errors + +## Examples -Specific examples of this include: +Specific examples of agents include: - [AI Plugins](agents/custom_agent_with_plugin_retrieval.ipynb): an implementation of an agent that is designed to be able to use all AI Plugins. - [Plug-and-PlAI (Plugins Database)](agents/custom_agent_with_plugin_retrieval_using_plugnplai.ipynb): an implementation of an agent that is designed to be able to use all AI Plugins retrieved from PlugNPlAI.