Merge branch 'master' into harrison/agent-docs-concepts

docs/docs/modules/agents/agent_types/index.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 0
+sidebar_position: 1
 ---
 
 # Agent Types

docs/docs/modules/agents/concepts.mdx

@@ -0,0 +1,111 @@
+---
+sidebar_position: 0
+---
+
+# Concepts
+
+
+The core idea of agents is to use a language model to choose a sequence of actions to take.
+In chains, a sequence of actions is hardcoded (in code).
+In agents, a language model is used as a reasoning engine to determine which actions to take and in which order.
+
+There are several key components here:
+
+## Schema
+
+LangChain has several abstractions to make working with agents easy.
+
+### AgentAction
+
+This is a dataclass that represents the action an agent should take.
+It has a `tool` property (which is the name of the tool that should be invoked) and a `tool_input` property (the input to that tool)
+
+### AgentFinish
+
+This represents the final result from an agent, when it is ready to return to the user.
+It contains a `return_values` key-value mapping, which contains the final agent output.
+Usually, this contains an `output` key containing a string that is the agent's response.
+
+### Intermediate Steps
+
+These represent previous agent actions and corresponding outputs from this CURRENT agent run.
+These are important to pass to future iteration so the agent knows what work it has already done.
+This is typed as a `List[Tuple[AgentAction, Any]]`.
+Note that observation is currently left as type `Any` to be maximally flexible.
+In practice, this is often a string.
+
+## Agent
+
+This is the chain responsible for deciding what step to take next.
+This is usually powered by a language model, a prompt, and an output parser.
+
+Different agents have different prompting styles for reasoning, different ways of encoding inputs, and different ways of parsing the output.
+For a full list of built-in agents see [agent types](/docs/modules/agents/agent_types/).
+You can also **easily build custom agents**, should you need further control.
+
+### Agent Inputs
+
+The inputs to an agent are a key-value mapping.
+There is only one required key: `intermediate_steps`, which corresponds to `Intermediate Steps` as described above.
+
+Generally, the PromptTemplate takes care of transforming these pairs into a format that can best be passed into the LLM.
+
+### Agent Outputs
+
+The output is the next action(s) to take or the final response to send to the user (`AgentAction`s or `AgentFinish`).
+Concretely, this can be typed as `Union[AgentAction, List[AgentAction], AgentFinish]`.
+
+The output parser is responsible for taking the raw LLM output and transforming it into one of these three types.
+
+## AgentExecutor
+
+The agent executor is the runtime for an agent.
+This is what actually calls the agent, executes the actions it chooses, passes the action outputs back to the agent, and repeats.
+In pseudocode, this looks roughly like:
+
+```python
+next_action = agent.get_action(...)
+while next_action != AgentFinish:
+    observation = run(next_action)
+    next_action = agent.get_action(..., next_action, observation)
+return next_action
+```
+
+While this may seem simple, there are several complexities this runtime handles for you, including:
+
+1. Handling cases where the agent selects a non-existent tool
+2. Handling cases where the tool errors
+3. Handling cases where the agent produces output that cannot be parsed into a tool invocation
+4. Logging and observability at all levels (agent decisions, tool calls) to stdout and/or to [LangSmith](/docs/langsmith).
+
+## Tools
+
+Tools are functions that an agent can invoke.
+The `Tool` abstraction consists of two components:
+
+1. The input schema for the tool. This tells the LLM what parameters are needed to call the tool. Without this, it will not know what the correct inputs are. These parameters should be sensibly named and described.
+2. The function to run. This is generally just a Python function that is invoked.
+
+
+### Considerations
+There are two important design considerations around tools:
+
+1. Giving the agent access to the right tools
+2. Describing the tools in a way that is most helpful to the agent
+
+Without thinking through both, you won't be able to build a working agent.
+If you don't give the agent access to a correct set of tools, it will never be able to accomplish the objectives you give it.
+If you don't describe the tools well, the agent won't know how to use them properly.
+
+LangChain provides a wide set of built-in tools, but also makes it easy to define your own (including custom descriptions).
+For a full list of built-in tools, see the [tools integrations section](/docs/integrations/tools/)
+
+## Toolkits
+
+For many common tasks, an agent will need a set of related tools.
+For this LangChain provides the concept of toolkits - groups of around 3-5 tools needed to accomplish specific objectives.
+For example, the GitHub toolkit has a tool for searching through GitHub issues, a tool for reading a file, a tool for commenting, etc.
+
+LangChain provides a wide set of toolkits to get started.
+For a full list of built-in toolkits, see the [toolkits integrations section](/docs/integrations/toolkits/)
+

docs/docs/modules/agents/how_to/_category_.yml

@@ -1,2 +1,2 @@
 label: 'How-to'
-position: 1
+position: 2

docs/docs/modules/agents/index.ipynb

@@ -22,80 +22,9 @@
     "In agents, a language model is used as a reasoning engine to determine which actions to take and in which order.\n",
     "\n",
     "## Concepts\n",
-    "There are several key components here:\n",
     "\n",
-    "### Agent\n",
-    "\n",
-    "This is the chain responsible for deciding what step to take next.\n",
-    "This is powered by a language model and a prompt.\n",
-    "The inputs to this chain are:\n",
-    "\n",
-    "1. Tools: Descriptions of available tools\n",
-    "2. User input: The high level objective\n",
-    "3. Intermediate steps: Any (action, tool output) pairs previously executed in order to achieve the user input\n",
-    "\n",
-    "The output is the next action(s) to take or the final response to send to the user (`AgentAction`s or `AgentFinish`). An action specifies a tool and the input to that tool. \n",
-    "\n",
-    "Different agents have different prompting styles for reasoning, different ways of encoding inputs, and different ways of parsing the output.\n",
-    "For a full list of built-in agents see [agent types](/docs/modules/agents/agent_types/).\n",
-    "You can also **easily build custom agents**, which we show how to do in the Get started section below.\n",
-    "\n",
-    "### Tools\n",
-    "\n",
-    "Tools are functions that an agent can invoke.\n",
-    "There are two important design considerations around tools:\n",
-    "\n",
-    "1. Giving the agent access to the right tools\n",
-    "2. Describing the tools in a way that is most helpful to the agent\n",
-    "\n",
-    "Without thinking through both, you won't be able to build a working agent.\n",
-    "If you don't give the agent access to a correct set of tools, it will never be able to accomplish the objectives you give it.\n",
-    "If you don't describe the tools well, the agent won't know how to use them properly.\n",
-    "\n",
-    "LangChain provides a wide set of built-in tools, but also makes it easy to define your own (including custom descriptions).\n",
-    "For a full list of built-in tools, see the [tools integrations section](/docs/integrations/tools/)\n",
-    "\n",
-    "### Toolkits\n",
-    "\n",
-    "For many common tasks, an agent will need a set of related tools.\n",
-    "For this LangChain provides the concept of toolkits - groups of around 3-5 tools needed to accomplish specific objectives.\n",
-    "For example, the GitHub toolkit has a tool for searching through GitHub issues, a tool for reading a file, a tool for commenting, etc.\n",
-    "\n",
-    "LangChain provides a wide set of toolkits to get started.\n",
-    "For a full list of built-in toolkits, see the [toolkits integrations section](/docs/integrations/toolkits/)\n",
-    "\n",
-    "### AgentExecutor\n",
-    "\n",
-    "The agent executor is the runtime for an agent.\n",
-    "This is what actually calls the agent, executes the actions it chooses, passes the action outputs back to the agent, and repeats.\n",
-    "In pseudocode, this looks roughly like:\n",
-    "\n",
-    "```python\n",
-    "next_action = agent.get_action(...)\n",
-    "while next_action != AgentFinish:\n",
-    "    observation = run(next_action)\n",
-    "    next_action = agent.get_action(..., next_action, observation)\n",
-    "return next_action\n",
-    "```\n",
-    "\n",
-    "While this may seem simple, there are several complexities this runtime handles for you, including:\n",
-    "\n",
-    "1. Handling cases where the agent selects a non-existent tool\n",
-    "2. Handling cases where the tool errors\n",
-    "3. Handling cases where the agent produces output that cannot be parsed into a tool invocation\n",
-    "4. Logging and observability at all levels (agent decisions, tool calls) to stdout and/or to [LangSmith](/docs/langsmith).\n",
-    "\n",
-    "### Other types of agent runtimes\n",
-    "\n",
-    "The `AgentExecutor` class is the main agent runtime supported by LangChain.\n",
-    "However, there are other, more experimental runtimes we also support.\n",
-    "These include:\n",
-    "\n",
-    "- [Plan-and-execute Agent](/docs/use_cases/more/agents/autonomous_agents/plan_and_execute)\n",
-    "- [Baby AGI](/docs/use_cases/more/agents/autonomous_agents/baby_agi)\n",
-    "- [Auto GPT](/docs/use_cases/more/agents/autonomous_agents/autogpt)\n",
-    "\n",
-    "You can also always create your own custom execution logic, which we show how to do below.\n",
+    "There are several key concepts to understand when building agents: Agents, AgentExecutor, Tools, Toolkits.\n",
+    "For an in depth explanation, please check out [this conceptual guide](./concepts)\n",
     "\n",
     "## Get started\n",
     "\n",

docs/docs/modules/agents/tools/index.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 # Tools