feat(oss): add multi-agent docs #352
Conversation
christian-bromann
requested review from
lnhsingh,
katmayb and
beklapko
as code owners
|
Preview ID generated: preview-cbmult-1756923077-adb1fe2 |
| * Context or memory grows too large for one agent to track effectively. | ||
| * Tasks require **specialization** (e.g., a planner, researcher, math expert). | ||
|
|
||
| Benefits include: |
There was a problem hiding this comment.
We could potentially cut out the benefits to reduce the amount of text
There was a problem hiding this comment.
+1, I think these are implicit
| 3. The **tool agent** returns results to the controller. | ||
| 4. The **controller** decides the next step or finishes. | ||
|
|
||
| ✅ Predictable, centralized routing.<br /> |
There was a problem hiding this comment.
Let's remove these bullet points -- I don't think they're correct
| 2. It passes control (and state) to the **next agent**. | ||
| 3. The **new agent** interacts directly with the user until it decides to hand off again or finish. | ||
|
|
||
| ✅ Flexible, more natural conversational flow between specialists.<br /> |
There was a problem hiding this comment.
Let's remove these bullet points -- I don't think they're correct
| | ----------------------------------------------------- | ------------ | -------- | | ||
| | Need centralized control over workflow? | ✅ Yes | ❌ No | | ||
| | Want agents to interact directly with the user? | ❌ No | ✅ Yes | | ||
| | Complex, human-like conversation between specialists? | ❌ Limited | ✅ Strong | |
There was a problem hiding this comment.
I don't understand the last entry -- let's remove it?
|
|
||
| ```python | ||
| from langgraph.prebuilt import create_react_agent | ||
| from langgraph_supervisor import create_supervisor |
There was a problem hiding this comment.
Let's remove the prebuilt? I don't think the package adds much value when users need to customize the behavior further -- it introduces it's own abstractions that are difficulty to reason about
src/oss/langchain-multi-agent.mdx
Outdated
| In this variant of the supervisor architecture, we define a supervisor agent which is responsible for calling sub-agents. The sub-agents are exposed to the supervisor as tools: | ||
|
|
||
| <Tabs> | ||
| <Tab title="Supervisor (from scratch)"> |
There was a problem hiding this comment.
| <Tab title="Supervisor (from scratch)"> | |
| <Tab title="Supervisor"> |
|
|
||
| ::: | ||
|
|
||
| ## Multi-agent architectures |
There was a problem hiding this comment.
Major: Do we need to describe the different architectures? Why can we not focus specifically on tool calling and handoffs and show how to implement the various patterns?
I don't think knowing that the agents are in a "network" adds much utility?
|
Preview ID generated: preview-cbmult-1756924758-fc814ff |
| You can also combine these patterns — e.g., use a top-level **tool-calling controller** for high-level routing, but allow **handoffs** within a team of related agents for smoother conversation. | ||
| </Tip> | ||
|
|
||
| ## How handoffs work |
There was a problem hiding this comment.
We're missing a bit of information about how the "active agent" is tracked
This means that supporting handoffs in your system requires tracking the currently active agent in the shared graph state, so the runtime always knows which agent is “in control.”
We might need a sentence somewhere about the graph state including an active_agent attribute and potentially explanation that when using multi-agent with handoffs the entrypoint into the graph is a routing node.
|
|
||
| The most important thing when building multi-agent systems is figuring out how the agents communicate. A common way for agents to communicate is via a shared list of messages in the graph state. | ||
|
|
||
| ### Context engineering |
There was a problem hiding this comment.
I suspect that as a user I'd need to see context engineering examples for both tools and handoffs to be able to understand how to do context engineering in each case.
The ones below are specifically for non-handoff tools (i.e., supervisor).
src/oss/langchain-multi-agent.mdx
Outdated
| ::: | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Supervisor" icon="user-crown"> |
There was a problem hiding this comment.
We can probably remove this example and recommend that users implement supervisor using tools?
|
|
||
| * A single agent has too many tools and makes poor decisions about which to use. | ||
| * Context or memory grows too large for one agent to track effectively. | ||
| * Tasks require **specialization** (e.g., a planner, researcher, math expert). |
There was a problem hiding this comment.
| * Tasks require **specialization** (e.g., a planner, researcher, math expert). | |
| * Sub-tasks require **specialization** (e.g., a planner, researcher, math expert). |
| | Pattern | How it Works | Control Flow | Example Use Case | | ||
| | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------ | | ||
| | **Tool Calling** | A central agent calls other agents as *tools*. The "tool" agents don't talk to the user directly — they just run their task and return results. | Centralized — all routing passes through the calling agent. | Task orchestration, structured workflows. | | ||
| | **Handoffs** | The current agent decides to **transfer control** to another agent. The active agent changes, and the user may continue interacting directly with the new agent. | Decentralized — agents can change who is active. | Multi-domain conversations, specialist takeover. | |
There was a problem hiding this comment.
This table format does not translate to mobile. Perhaps two accordions with How it Works, Control Flow, and Example as subjeaders
There was a problem hiding this comment.
The example subheader could then maybe have code snippet dropdowns? or might become too much content
|
Preview ID generated: preview-cbmult-1756929036-88d1417 |
|
Preview ID generated: preview-cbmult-1756929388-b5c9326 |
|
Preview ID generated: preview-cbmult-1757014745-55d972b |
|
Should this be closed or adapted to match #418? @christian-bromann @eyurtsev |
|
Merged in another form |
Adding docs on multi agent.