langchain - 💡(How to fix) Fix agent swarm orchestrator for multi-agent coordination [1 comments, 2 participants]

Checked other resources

• This is a feature request, not a bug report or usage question.
• I added a clear and descriptive title that summarizes the feature request.
• I used the GitHub search to find a similar feature request and didn't find it.
• I checked the LangChain documentation and API reference to see if this feature already exists.
• This is not related to the langchain-community package.

Package (Required)

• langchain
• langchain-openai
• langchain-anthropic
• langchain-classic
• langchain-core
• langchain-model-profiles
• langchain-tests
• langchain-text-splitters
• langchain-chroma
• langchain-deepseek
• langchain-exa
• langchain-fireworks
• langchain-groq
• langchain-huggingface
• langchain-mistralai
• langchain-nomic
• langchain-ollama
• langchain-openrouter
• langchain-perplexity
• langchain-qdrant
• langchain-xai
• Other / not sure / general

Feature Description

A create_swarm_orchestrator() function in langchain.agents that takes a list of LangChain agents and turns them into a coordinated multi-agent swarm built on LangGraph.

The function would accept:

• agents — a list of agents (any Runnable) to orchestrate
• delegation_policy — either "auto" for LLM-based routing or a custom callable that decides which agent handles the next turn
• max_rounds — maximum routing rounds to prevent infinite loops
• shared_state — optional custom state schema (defaults to a MessagesState-compatible TypedDict)
• checkpointer — optional checkpointer for persistence and human-in-the-loop support

It would return a compiled LangGraph StateGraph that behaves exactly like a standard LangChain agent, supporting .invoke(), .astream(), and .astream_events(). This gives users a single function call to go from multiple independent agents to a fully working swarm with routing, round-limiting, and shared conversation state — without needing to manually build graph nodes and edges.

Use Case

When building multi-agent applications — such as a research + writing pipeline, a customer support triage system, or a coding assistant with specialized sub-agents — developers need to coordinate multiple LangChain agents that each handle a different part of the task. Today, this requires manually building a LangGraph StateGraph, writing routing logic, wiring up edges between nodes, and implementing round-limiting to prevent infinite loops. This is roughly 50-100 lines of boilerplate that every multi-agent project has to duplicate, and it's easy to get wrong (e.g., forgetting to cap routing rounds, losing message history between agents, or mishandling agent name resolution). A high-level create_swarm_orchestrator() function would let developers go from multiple agents to a working swarm in a single function call — the same way create_agent() already simplifies single-agent setup. This removes boilerplate, reduces bugs, and makes the multi-agent pattern accessible to users who aren't deeply familiar with LangGraph internals.

Proposed Solution

A create_swarm_orchestrator() function in langchain.agents that builds a LangGraph StateGraph under the hood:

1. One graph node per agent — each agent (any Runnable) becomes a node in the graph
2. A router node that delegates to the next agent based on a configurable delegation_policy:
   • "auto" — uses a lightweight LLM (gpt-4o-mini) with structured output to decide routing
   • Custom callable — user provides a function that accepts the state and returns the next agent name or "FINISH"
3. Shared SwarmState — a MessagesState-compatible TypedDict so every agent sees the full conversation history and tool results
4. Round-limiting — a max_rounds parameter tracked in the state to prevent infinite routing loops without relying on recursion_limit
5. Returns a compiled StateGraph — fully compatible with .invoke(), .astream(), .astream_events(), and optional checkpointer for persistence

Example API:

from langchain.agents import create_agent, create_swarm_orchestrator

researcher = create_agent("openai:gpt-4o", tools=[search_tool], name="researcher")
writer = create_agent("openai:gpt-4o", tools=[write_tool], name="writer")

swarm = create_swarm_orchestrator(
    agents=[researcher, writer],
    delegation_policy="auto",
    max_rounds=10,
)

result = swarm.invoke({"messages": [HumanMessage(content="Write a report")]})


### Alternatives Considered

1. **Manual LangGraph wiring** — Building the `StateGraph`, adding nodes/edges, and writing routing logic by hand. This works but produces 50-100 lines of boilerplate per project and is error-prone (easy to forget round-limiting, lose message state, or mishandle agent names).

2. **LangGraph's built-in `Command`/`Send` directly** — Using low-level LangGraph primitives for agent delegation. This gives full control but requires deep familiarity with LangGraph internals, which is a barrier for many LangChain users.

3. **Third-party multi-agent frameworks (e.g., CrewAI, AutoGen)** — These solve the orchestration problem but introduce a separate dependency and don't integrate natively with LangChain's `Runnable` interface, tool ecosystem, or streaming/checkpointing capabilities.

A built-in `create_swarm_orchestrator()` is preferable because it stays within the LangChain ecosystem, follows established patterns (mirrors the `create_agent()` API), and gives users a one-line upgrade path from single-agent to multi-agent without learning a new framework.


### Additional Context

- I have a working implementation on my fork with 6 passing unit tests (zero network calls): [feature/agent-swarm-orchestrator](https://github.com/josephkamau32/langchain/tree/feature/agent-swarm-orchestrator)
- The implementation lives in `libs/langchain_v1/langchain/agents/swarm_orchestrator.py` (277 lines) and follows existing code patterns in the `agents` package
- Tests cover: happy path, custom delegation policy, invalid input validation, async streaming, and max rounds enforcement
- This was developed with the assistance of an AI coding agent; all code has been reviewed and tested by me