state machine wip #1921
Merged
state machine wip #1921
+341
−45
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
|
Mintlify preview ID generated: preview-eugene-1765835478-b5aff5c |
Contributor
|
Mintlify preview ID generated: preview-eugene-1765853807-d9a7052 |
Contributor
|
Mintlify preview ID generated: preview-eugene-1765856625-d223354 |
Contributor
|
Mintlify preview ID generated: preview-eugene-1765856913-998ebf6 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors the "State machine" pattern documentation to align it with the "handoffs" terminology and expand the implementation approaches. The changes clarify that state machines can be implemented using either middleware-based configuration changes or multi-agent subgraphs with handoff tools, providing a more comprehensive view of this architectural pattern.
Key changes:
- Renamed the "State machine" section to "State machine (handoffs)" to align with industry terminology
- Expanded documentation to cover both single-agent-with-middleware and multiple-agent-subgraphs implementations
- Added comprehensive code examples for both Python and TypeScript showing handoff patterns
- Updated the pattern description table and internal references throughout the document
- Removed a comparative Tip from the customer-support-state-machine tutorial that was no longer accurate
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/oss/langchain/multi-agent.mdx | Updated state machine pattern documentation: renamed heading to include "(handoffs)", updated table description, added new section on multiple agent subgraphs with complete examples, updated link references, changed diagram from state machine to sequence diagram, revised key characteristics, and improved warning text about stateful routers |
| src/oss/langchain/customer-support-state-machine.mdx | Removed outdated Tip block comparing state machine efficiency to handoff-based approaches since the parent document now presents handoffs as a valid implementation approach |
|
|
||
| <Warning> | ||
| **This is challenging.** Maintaining coherent history across multiple agents is difficult, especially when agents run in parallel. Agents can become confused about context or produce inconsistent responses. Synthesizing results also becomes harder—you need to track which agents have responded and how to combine partial results across turns. Consider the [state machine pattern](#state-machine) or [subagents pattern](#subagents) instead—both are simpler to reason about. | ||
| **Stateful routers require custom history management.** If the router switches between agents across turns, conversations may not feel fluid to end users when agents have different tones or prompts. With parallel invocation, you'll need to maintain history at the router level (inputs and synthesized outputs) and leverage this history in routing logic. Consider the [state machine pattern](#state-machine) or [subagents pattern](#subagents) instead—both provide clearer semantics for multi-turn conversations. |
There was a problem hiding this comment.
The anchor link #state-machine does not match the actual heading "State machine (handoffs)" which creates the anchor #state-machine-handoffs. Update this link to use the correct anchor.
Suggested change
| **Stateful routers require custom history management.** If the router switches between agents across turns, conversations may not feel fluid to end users when agents have different tones or prompts. With parallel invocation, you'll need to maintain history at the router level (inputs and synthesized outputs) and leverage this history in routing logic. Consider the [state machine pattern](#state-machine) or [subagents pattern](#subagents) instead—both provide clearer semantics for multi-turn conversations. | |
| **Stateful routers require custom history management.** If the router switches between agents across turns, conversations may not feel fluid to end users when agents have different tones or prompts. With parallel invocation, you'll need to maintain history at the router level (inputs and synthesized outputs) and leverage this history in routing logic. Consider the [state machine pattern](#state-machine-handoffs) or [subagents pattern](#subagents) instead—both provide clearer semantics for multi-turn conversations. |
| </Tip> | ||
|
|
||
| **Common mechanisms:** These patterns share common mechanisms for coordinating multi-agent behavior. Most rely on **tool calling** as the primary coordination mechanism—tools can invoke subagents ([subagents](#subagents)), update state to trigger routing or behavior changes ([state machine](#state-machine)), load context on-demand ([skills](#skills)), or even invoke entire multi-agent systems (like wrapping a [router](#router) as a tool). | ||
| **Common mechanisms:** These patterns share common mechanisms for coordinating multi-agent behavior. Most rely on **tool calling** as the primary coordination mechanism—tools can invoke sub-agents ([supervisor](#supervisor)), update state to trigger routing or behavior changes ([state machine](#state-machine-handoffs)), load context on-demand ([skills](#skills)), or even invoke entire multi-agent systems (like wrapping a [router](#router) as a tool). |
There was a problem hiding this comment.
The anchor link #supervisor references a section that doesn't exist on this page. Based on the context and the structure of the document, this should likely link to #subagents instead, since "supervisor" is mentioned as an alternative name for the main agent in the subagents pattern.
Suggested change
| **Common mechanisms:** These patterns share common mechanisms for coordinating multi-agent behavior. Most rely on **tool calling** as the primary coordination mechanism—tools can invoke sub-agents ([supervisor](#supervisor)), update state to trigger routing or behavior changes ([state machine](#state-machine-handoffs)), load context on-demand ([skills](#skills)), or even invoke entire multi-agent systems (like wrapping a [router](#router) as a tool). | |
| **Common mechanisms:** These patterns share common mechanisms for coordinating multi-agent behavior. Most rely on **tool calling** as the primary coordination mechanism—tools can invoke sub-agents ([supervisor](#subagents)), update state to trigger routing or behavior changes ([state machine](#state-machine-handoffs)), load context on-demand ([skills](#skills)), or even invoke entire multi-agent systems (like wrapping a [router](#router) as a tool). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
Type of change
Type: [Replace with: New documentation page / Update existing documentation / Fix typo/bug/link/formatting / Remove outdated content / Other]
Related issues/PRs
Checklist
docs devsrc/docs.jsonif needed(Internal team members only / optional): Create a preview deployment as necessary using the Create Preview Branch workflow
Additional notes