improve agent documentation (#4062)

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
 ---------

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.