Docs: Re-organize conceptual docs (#27047)

Reorganization of conceptual documentation

---------

Co-authored-by: Lance Martin <[email protected]>
Co-authored-by: Lance Martin <[email protected]>
Co-authored-by: Harrison Chase <[email protected]>
Co-authored-by: Bagatur <[email protected]>

docs/docs/concepts/agents.mdx

@@ -0,0 +1,25 @@
+# Agents
+
+By themselves, language models can't take actions - they just output text. Agents are systems that take a high-level task and use an LLM as a reasoning engine to decide what actions to take and execute those actions.
+
+[LangGraph](/docs/concepts/architecture#langgraph) is an extension of LangChain specifically aimed at creating highly controllable and customizable agents. We recommend that you use LangGraph for building agents.
+
+Please see the following resources for more information:
+
+* LangGraph docs on [common agent architectures](https://langchain-ai.github.io/langgraph/concepts/agentic_concepts/)
+* [Pre-built agents in LangGraph](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent)
+
+## Legacy agent concept: AgentExecutor
+
+LangChain previously introduced the `AgentExecutor` as a runtime for agents. 
+While it served as an excellent starting point, its limitations became apparent when dealing with more sophisticated and customized agents. 
+As a result, we're gradually phasing out `AgentExecutor` in favor of more flexible solutions in LangGraph.
+
+### Transitioning from AgentExecutor to langgraph
+
+If you're currently using `AgentExecutor`, don't worry! We've prepared resources to help you:
+
+1. For those who still need to use `AgentExecutor`, we offer a comprehensive guide on [how to use AgentExecutor](/docs/how_to/agent_executor).
+
+2. However, we strongly recommend transitioning to LangGraph for improved flexibility and control. To facilitate this transition, we've created a detailed [migration guide](/docs/how_to/migrate_agent) to help you move from `AgentExecutor` to LangGraph seamlessly.
+

docs/docs/concepts/architecture.mdx

@@ -0,0 +1,78 @@
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Architecture
+
+LangChain as a framework consists of a number of packages.
+
+<ThemedImage
+    alt="Diagram outlining the hierarchical organization of the LangChain framework, displaying the interconnected parts across multiple layers."
+    sources={{
+        light: useBaseUrl('/svg/langchain_stack_062024.svg'),
+        dark: useBaseUrl('/svg/langchain_stack_062024_dark.svg'),
+    }}
+    title="LangChain Framework Overview"
+    style={{ width: "100%" }}
+/>
+
+
+## langchain-core
+
+This package contains base abstractions of different components and ways to compose them together.
+The interfaces for core components like LLMs, vector stores, retrievers and more are defined here.
+No third party integrations are defined here.
+The dependencies are kept purposefully very lightweight.
+
+## langchain
+
+The main `langchain` package contains chains, agents, and retrieval strategies that make up an application's cognitive architecture.
+These are NOT third party integrations.
+All chains, agents, and retrieval strategies here are NOT specific to any one integration, but rather generic across all integrations.
+
+## langchain-community
+
+This package contains third party integrations that are maintained by the LangChain community.
+Key partner packages are separated out (see below).
+This contains all integrations for various components (LLMs, vector stores, retrievers).
+All dependencies in this package are optional to keep the package as lightweight as possible.
+
+## Partner packages
+
+While the long tail of integrations is in `langchain-community`, we split popular integrations into their own packages (e.g. `langchain-openai`, `langchain-anthropic`, etc). This was done in order to improve support for these important integrations.
+
+For more information see:
+
+* A list [LangChain integrations](/docs/integrations/providers/)
+* The [LangChain API Reference](https://python.langchain.com/api_reference/) where you can find detailed information about the API reference of each partner package.
+
+## LangGraph
+
+`langgraph` is an extension of `langchain` aimed at building robust and stateful multi-actor applications with LLMs by modeling steps as edges and nodes in a graph.
+
+LangGraph exposes high level interfaces for creating common types of agents, as well as a low-level API for composing custom flows.
+
+:::info[Further reading]
+
+* See our LangGraph overview [here](https://langchain-ai.github.io/langgraph/concepts/high_level/#core-principles).
+* See our LangGraph Academy Course [here](https://academy.langchain.com/courses/intro-to-langgraph).
+
+:::
+
+## LangServe
+
+A package to deploy LangChain chains as REST APIs. Makes it easy to get a production ready API up and running.
+
+:::important
+LangServe is designed to primarily deploy simple Runnables and work with well-known primitives in langchain-core.
+
+If you need a deployment option for LangGraph, you should instead be looking at LangGraph Cloud (beta) which will be better suited for deploying LangGraph applications.
+:::
+
+For more information, see the [LangServe documentation](/docs/langserve).
+
+
+## LangSmith
+
+A developer platform that lets you debug, test, evaluate, and monitor LLM applications.
+
+For more information, see the [LangSmith documentation](https://docs.smith.langchain.com)

docs/docs/concepts/async.mdx

@@ -0,0 +1,81 @@
+# Async programming with langchain
+
+:::info Prerequisites
+* [Runnable interface](/docs/concepts/runnables)
+* [asyncio](https://docs.python.org/3/library/asyncio.html)
+:::
+
+LLM based applications often involve a lot of I/O-bound operations, such as making API calls to language models, databases, or other services. Asynchronous programming (or async programming) is a paradigm that allows a program to perform multiple tasks concurrently without blocking the execution of other tasks, improving efficiency and responsiveness, particularly in I/O-bound operations.
+
+:::note
+You are expected to be familiar with asynchronous programming in Python before reading this guide. If you are not, please find appropriate resources online to learn how to program asynchronously in Python.
+This guide specifically focuses on what you need to know to work with LangChain in an asynchronous context, assuming that you are already familiar with asynch
+:::
+
+## Langchain asynchronous apis
+
+Many LangChain APIs are designed to be asynchronous, allowing you to build efficient and responsive applications.
+
+Typically, any method that may perform I/O operations (e.g., making API calls, reading files) will have an asynchronous counterpart.
+
+In LangChain, async implementations are located in the same classes as their synchronous counterparts, with the asynchronous methods having an "a" prefix. For example, the synchronous `invoke` method has an asynchronous counterpart called `ainvoke`.
+
+Many components of LangChain implement the [Runnable Interface](/docs/concepts/runnables), which includes support for asynchronous execution. This means that you can run Runnables asynchronously using the `await` keyword in Python.
+
+```python
+await some_runnable.ainvoke(some_input)
+```
+
+Other components like [Embedding Models](/docs/concepts/embedding_models) and [VectorStore](/docs/concepts/vectorstores) that do not implement the [Runnable Interface](/docs/concepts/runnables) usually still follow the same rule and include the asynchronous version of method in the same class with an "a" prefix.
+
+For example,
+
+```python
+await some_vectorstore.aadd_documents(documents)
+```
+
+Runnables created using the [LangChain Expression Language (LCEL)](/docs/concepts/lcel) can also be run asynchronously as they implement
+the full [Runnable Interface](/docs/concepts/runnables).
+
+Fore more information, please review the [API reference](https://python.langchain.com/api_reference/) for the specific component you are using.
+
+## Delegation to sync methods
+
+Most popular LangChain integrations implement asynchronous support of their APIs. For example, the `ainvoke` method of many ChatModel implementations uses the `httpx.AsyncClient` to make asynchronous HTTP requests to the model provider's API.
+
+When an asynchronous implementation is not available, LangChain tries to provide a default implementation, even if it incurs
+a **slight** overhead.
+
+By default, LangChain will delegate the execution of a unimplemented asynchronous methods to the synchronous counterparts. LangChain almost always assumes that the synchronous method should be treated as a blocking operation and should be run in a separate thread.
+This is done using [asyncio.loop.run_in_executor](https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor) functionality provided by the `asyncio` library. LangChain uses the default executor provided by the `asyncio` library, which lazily initializes a thread pool executor with a default number of threads that is reused in the given event loop. While this strategy incurs a slight overhead due to context switching between threads, it guarantees that every asynchronous method has a default implementation that works out of the box.
+
+## Performance
+
+Async code in LangChain should generally perform relatively well with minimal overhead out of the box, and is unlikely
+to be a bottleneck in most applications.
+
+The two main sources of overhead are:
+
+1. Cost of context switching between threads when [delegating to synchronous methods](#delegation-to-sync-methods). This can be addressed by providing a native asynchronous implementation.
+2. In [LCEL](/docs/concepts/lcel) any "cheap functions" that appear as part of the chain will be either scheduled as tasks on the event loop (if they are async) or run in a separate thread (if they are sync), rather than just be run inline.
+
+The latency overhead you should expect from these is between tens of microseconds to a few milliseconds.
+
+A more common source of performance issues arises from users accidentally blocking the event loop by calling synchronous code in an async context (e.g., calling `invoke` rather than `ainvoke`).
+
+## Compatibility
+
+LangChain is only compatible with the `asyncio` library, which is distributed as part of the Python standard library. It will not work with other async libraries like `trio` or `curio`.
+
+In Python 3.9 and 3.10, [asyncio's tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) did not
+accept a `context` parameter. Due to this limitation, LangChain cannot automatically propagate the `RunnableConfig` down the call chain
+in certain scenarios.
+
+If you are experiencing issues with streaming, callbacks or tracing in async code and are using Python 3.9 or 3.10, this is a likely cause.
+
+Please read [Propagation RunnableConfig](/docs/concepts/runnables#propagation-RunnableConfig) for more details to learn how to propagate the `RunnableConfig` down the call chain manually (or upgrade to Python 3.11 where this is no longer an issue).
+
+## How to use in ipython and jupyter notebooks
+
+As of IPython 7.0, IPython supports asynchronous REPLs. This means that you can use the `await` keyword in the IPython REPL and Jupyter Notebooks without any additional setup. For more information, see the [IPython blog post](https://blog.jupyter.org/ipython-7-0-async-repl-a35ce050f7f7).
+

docs/docs/concepts/callbacks.mdx

@@ -0,0 +1,73 @@
+# Callbacks
+
+:::note Prerequisites
+- [Runnable interface](/docs/concepts/#runnable-interface)
+:::
+
+LangChain provides a callbacks system that allows you to hook into the various stages of your LLM application. This is useful for logging, monitoring, streaming, and other tasks.
+
+You can subscribe to these events by using the `callbacks` argument available throughout the API. This argument is list of handler objects, which are expected to implement one or more of the methods described below in more detail.
+
+## Callback events
+
+| Event            | Event Trigger                               | Associated Method     |
+|------------------|---------------------------------------------|-----------------------|
+| Chat model start | When a chat model starts                    | `on_chat_model_start` |
+| LLM start        | When a llm starts                           | `on_llm_start`        |
+| LLM new token    | When an llm OR chat model emits a new token | `on_llm_new_token`    |
+| LLM ends         | When an llm OR chat model ends              | `on_llm_end`          |
+| LLM errors       | When an llm OR chat model errors            | `on_llm_error`        |
+| Chain start      | When a chain starts running                 | `on_chain_start`      |
+| Chain end        | When a chain ends                           | `on_chain_end`        |
+| Chain error      | When a chain errors                         | `on_chain_error`      |
+| Tool start       | When a tool starts running                  | `on_tool_start`       |
+| Tool end         | When a tool ends                            | `on_tool_end`         |
+| Tool error       | When a tool errors                          | `on_tool_error`       |
+| Agent action     | When an agent takes an action               | `on_agent_action`     |
+| Agent finish     | When an agent ends                          | `on_agent_finish`     |
+| Retriever start  | When a retriever starts                     | `on_retriever_start`  |
+| Retriever end    | When a retriever ends                       | `on_retriever_end`    |
+| Retriever error  | When a retriever errors                     | `on_retriever_error`  |
+| Text             | When arbitrary text is run                  | `on_text`             |
+| Retry            | When a retry event is run                   | `on_retry`            |
+
+## Callback handlers
+
+Callback handlers can either be `sync` or `async`:
+
+* Sync callback handlers implement the [BaseCallbackHandler](https://python.langchain.com/api_reference/core/callbacks/langchain_core.callbacks.base.BaseCallbackHandler.html) interface.
+* Async callback handlers implement the [AsyncCallbackHandler](https://python.langchain.com/api_reference/core/callbacks/langchain_core.callbacks.base.AsyncCallbackHandler.html) interface.
+
+During run-time LangChain configures an appropriate callback manager (e.g., [CallbackManager](https://python.langchain.com/api_reference/core/callbacks/langchain_core.callbacks.manager.CallbackManager.html) or [AsyncCallbackManager](https://python.langchain.com/api_reference/core/callbacks/langchain_core.callbacks.manager.AsyncCallbackManager.html) which will be responsible for calling the appropriate method on each "registered" callback handler when the event is triggered.
+
+## Passing callbacks
+
+The `callbacks` property is available on most objects throughout the API (Models, Tools, Agents, etc.) in two different places:
+
+- **Request time callbacks**: Passed at the time of the request in addition to the input data.
+Available on all standard `Runnable` objects. These callbacks are INHERITED by all children
+of the object they are defined on. For example, `chain.invoke({"number": 25}, {"callbacks": [handler]})`.
+- **Constructor callbacks**: `chain = TheNameOfSomeChain(callbacks=[handler])`. These callbacks
+are passed as arguments to the constructor of the object. The callbacks are scoped
+only to the object they are defined on, and are **not** inherited by any children of the object.
+
+:::warning
+Constructor callbacks are scoped only to the object they are defined on. They are **not** inherited by children
+of the object.
+:::
+
+If you're creating a custom chain or runnable, you need to remember to propagate request time
+callbacks to any child objects.
+
+:::important Async in Python<=3.10
+
+Any `RunnableLambda`, a `RunnableGenerator`, or `Tool` that invokes other runnables
+and is running `async` in python<=3.10, will have to propagate callbacks to child
+objects manually. This is because LangChain cannot automatically propagate
+callbacks to child objects in this case.
+
+This is a common reason why you may fail to see events being emitted from custom
+runnables or tools.
+:::
+
+For specifics on how to use callbacks, see the [relevant how-to guides here](/docs/how_to/#callbacks).

docs/docs/concepts/chat_history.mdx

@@ -0,0 +1,46 @@
+# Chat history
+
+:::info Prerequisites
+
+- [Messages](/docs/concepts/messages)
+- [Chat models](/docs/concepts/chat_models)
+- [Tool calling](/docs/concepts/tool_calling)
+:::
+
+Chat history is a record of the conversation between the user and the chat model. It is used to maintain context and state throughout the conversation. The chat history is sequence of [messages](/docs/concepts/messages), each of which is associated with a specific [role](/docs/concepts/messages#role), such as "user", "assistant", "system", or "tool".
+
+## Conversation patterns
+
+![Conversation patterns](/img/conversation_patterns.png)
+
+Most conversations start with a **system message** that sets the context for the conversation. This is followed by a **user message** containing the user's input, and then an **assistant message** containing the model's response.
+
+The **assistant** may respond directly to the user or if configured with tools request that a [tool](/docs/concepts/tool_calling) be invoked to perform a specific task.
+
+So a full conversation often involves a combination of two patterns of alternating messages:
+
+1. The **user** and the **assistant** representing a back-and-forth conversation.
+2. The **assistant** and **tool messages** representing an ["agentic" workflow](/docs/concepts/agents) where the assistant is invoking tools to perform specific tasks.
+
+## Managing chat history
+
+Since chat models have a maximum limit on input size, it's important to manage chat history and trim it as needed to avoid exceeding the [context window](/docs/concepts/chat_models#context_window).
+
+While processing chat history, it's essential to preserve a correct conversation structure. 
+
+Key guidelines for managing chat history:
+
+- The conversation should follow one of these structures:
+    - The first message is either a "user" message or a "system" message, followed by a "user" and then an "assistant" message.
+    - The last message should be either a "user" message or a "tool" message containing the result of a tool call.
+- When using [tool calling](/docs/concepts/tool_calling), a "tool" message should only follow an "assistant" message that requested the tool invocation.
+
+:::tip
+Understanding correct conversation structure is essential for being able to properly implement
+[memory](https://langchain-ai.github.io/langgraph/concepts/memory/) in chat models.
+:::
+
+## Related resources
+
+- [How to trim messages](https://python.langchain.com/docs/how_to/trim_messages/)
+- [Memory guide](https://langchain-ai.github.io/langgraph/concepts/memory/) for information on implementing short-term and long-term memory in chat models using [LangGraph](https://langchain-ai.github.io/langgraph/).