LangGraph Multi-Agent Guide: Build AI Workflows Fast

As large language models (LLMs) evolve rapidly, AI Agent technology has become a core direction for engineering development. Single-agent solutions struggle to handle multi-step, complex business workflows such as information collection, data analysis and report writing. Long prompt engineering, unstable execution logic and frequent task interruptions are common pain points. Multi-agent architecture solves these problems by dividing labor among specialized agents, significantly improving task completion accuracy and operational stability. This practical guide elaborates on how to build a functional multi-agent system based on LangGraph, a mainstream orchestration framework developed by the LangChain team. Starting from demand analysis, framework introduction, environment deployment, core logic coding to advanced feature expansion and framework selection suggestions, this article presents a complete and executable development process. All test data, code cases and framework comparison indicators are derived from actual development practices, helping AI developers quickly master multi-agent development skills. The whole deployment and commissioning process can be completed within 20 minutes.

1. Why Choose Multi-Agent Architecture: Solve the Pain Points of Single-Agent Workflows

In practical internal tool development, the author initially adopted a single-agent solution to implement a topic research tool. The core requirement is to let AI automatically complete full-link work including information retrieval, key content sorting and formal report generation. In the single-agent mode, one agent is responsible for all operations such as search, content analysis and document writing simultaneously, which brings prominent practical problems.

In terms of prompt management, the single agent requires more than 2,000 tokens of detailed instruction prompts to constrain multiple tasks. Excessively long prompts not only increase token consumption but also lead to logic confusion for the LLM. In terms of execution stability, in 10 consecutive tests, the single-agent system failed 3 to 4 times. Typical failures include forgetting to generate reports after finishing information retrieval, or jumping back to search tasks halfway through writing. After splitting the single agent into multiple dedicated agents with clear division of labor, each agent only undertakes a single type of work. The prompt length of each agent is controlled between 200 and 300 tokens, which greatly reduces the burden of instruction understanding. In the same 10 rounds of repeated tests, the multi-agent system successfully delivered complete reports every time, and the task completion accuracy rose from about 60% to nearly 100%.

It is necessary to clarify the applicable scenarios of multi-agent architecture to avoid over-engineering. Multi-agent is not a universal solution. For simple tasks such as paragraph translation and short article summarization, a single agent or direct LLM API calls are more appropriate. Adding multi-agent links will instead increase additional invocation overhead and potential error points. The standard for adopting a multi-agent system is clear: when a task contains more than two different types of operations and there is an obvious sequential execution relationship between operations, multi-agent orchestration can exert its maximum value. Typical scenarios include end-to-end research reports, automated operation and maintenance workflows, and multi-module content creation.

2. Introduction to LangGraph: Core Advantages and Applicable Scenarios

LangGraph is an open-source multi-agent orchestration framework launched by the LangChain team. Its core design philosophy is to model agent workflows as directed graphs. In this architecture, each node corresponds to an independent agent or a single operation step, and edges define the execution sequence, conditional branches and logical jumps between nodes. As of now, the project has accumulated more than 8,200 stars on GitHub, and it has become one of the mainstream frameworks for enterprise-level multi-agent development.

Compared with popular peer frameworks such as AutoGen and CrewAI, LangGraph has distinct technical characteristics and core strengths: First, the graph-based workflow is intuitive and easy to debug. Developers can clearly view the input and output of each node during operation, quickly locate abnormal links in complex workflows, and greatly improve the efficiency of troubleshooting. Second, it has built-in state persistence (checkpoint) capability. If the agent workflow is interrupted due to API timeout, network fluctuations and other reasons during operation, the system can resume execution from the breakpoint without restarting the whole task, which is very suitable for long-running production tasks. Third, it natively supports the human-in-the-loop mechanism. Developers can set manual confirmation nodes in the workflow. When the execution reaches the specified link, the system will automatically pause and wait for human review and confirmation before continuing, which meets the compliance and audit requirements of enterprise business.

Meanwhile, LangGraph also has its own scope of adaptation and limitations. It is not suitable for simple single-turn dialogue or pure text generation tasks without tool invocation. For such lightweight demands, directly calling the native LLM API is more efficient, and introducing the LangGraph framework will bring redundant engineering costs. For complex workflows requiring conditional loops, result retry, state persistence and manual intervention, LangGraph is the optimal choice.

3. Environment Deployment and Basic Configuration

3.1 Operating Environment Requirements

This project relies on the Python runtime environment. The basic requirement is Python 3.10 or above. Developers need to install four core dependency libraries through the pip tool, with the specified versions to ensure compatibility. The installation command is as follows:

pip install langgraph==1.1.6 langchain-core==0.3.29 langchain-openai==0.3.8 python-dotenv==1.0.1

3.2 API Key Configuration

Create a .env file in the root directory of the project to store the LLM API key, which realizes decoupling of sensitive information and code. The file content format is as follows:

OPENAI_API_KEY=sk-your-key-here

3.3 Environment Verification

After completing the installation and configuration, run the following command in the terminal to verify whether LangGraph is installed successfully:

python -c "import langgraph; print(f'LangGraph {langgraph.__version__}')"

The normal output result is LangGraph 1.1.6, indicating that the environment is built successfully. The total API cost for running the complete tutorial is controlled within 2 US dollars, and the actual consumption of a single complete process is extremely low.

4. Core Development: State Definition, Agent Node Creation and Graph Assembly

4.1 Define Shared State (State)

State is the core concept of LangGraph. All agents in the system share a unified state object. Each agent reads data from the state before execution and writes the execution results back to the state after completion to realize data interaction between nodes. For the research report scenario, we define the ResearchState data structure based on TypedDict, covering research topics, search results, analysis points, final reports and message records.

It is a common pitfall in development that the messages field must use Annotated[list, add_messages] instead of a simple list. The add_messages function is a built-in reducer of LangGraph, which realizes the incremental appending of historical messages rather than overwriting. Ignoring this setting will cause all historical message data to be lost after each node runs. The complete state definition code is as follows:

from typing import TypedDict, Annotated
from langgraph.graph import add_messages

class ResearchState(TypedDict):
    topic: str
    search_results: list[str]
    analysis: str
    report: str
    messages: Annotated[list, add_messages]

4.2 Build Three Dedicated Agent Nodes

According to the business process of "search → analysis → writing", we divide the workflow into three independent agents, each responsible for a single link. All agents use GPT-4o as the underlying LLM and set temperature=0 to ensure stable output results.

1. Search Agent: Obtain the research topic from the state, invoke the search capability to collect relevant information, and store the search results in the state. In the demonstration environment, the LLM is used to simulate the search API. In actual projects, it can be connected to professional search tools such as Tavily and Bing.

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

llm = ChatOpenAI(model="gpt-4o", temperature=0)

def search_agent(state: ResearchState) -> dict:
    topic = state["topic"]
    response = llm.invoke([
        SystemMessage(content="You are a search engine. Return 5 pieces of relevant information according to the topic, each within 50 words, listed by number. Only return facts without comments."),
        HumanMessage(content=f"Search: {topic}")
    ])
    return {
        "search_results": [response.content],
        "messages": [HumanMessage(content=f"Search completed: collected materials about {topic}")]
    }

2. Analysis Agent: Read the search results in the state, extract 3 to 5 core key points, and write the analysis content back to the state.

def analysis_agent(state: ResearchState) -> dict:
    results = "\n".join(state["search_results"])
    response = llm.invoke([
        SystemMessage(content="You are an analyst. Extract 3-5 key points from the search results, one sentence for each point."),
        HumanMessage(content=f"Search results:\n{results}")
    ])
    return {
        "analysis": response.content,
        "messages": [HumanMessage(content="Analysis completed")]
    }

3. Writing Agent: Generate a standard research report based on the analysis points, with a specified length and structure, and finally output the complete report to the state.

def writer_agent(state: ResearchState) -> dict:
    response = llm.invoke([
        SystemMessage(content="You are a technical report writer. Write a 300-word research report according to the key points. Structure: 2 sentences for background, segmented key points, 1 sentence for conclusion."),
        HumanMessage(content=f"Topic: {state['topic']}\nKey points:\n{state['analysis']}")
    ])
    return {
        "report": response.content,
        "messages": [HumanMessage(content="Report writing completed")]
    }

4.3 Assemble the Workflow Graph

Assemble all agent nodes into a complete directed graph through StateGraph, define the execution sequence, and support linear processes and conditional branch logic.

1. Basic Linear Workflow: The simplest execution logic is to run in the order of search → analysis → writing.

from langgraph.graph import StateGraph, START, END

graph = StateGraph(ResearchState)
graph.add_node("search", search_agent)
graph.add_node("analyze", analysis_agent)
graph.add_node("write", writer_agent)

graph.add_edge(START, "search")
graph.add_edge("search", "analyze")
graph.add_edge("analyze", "write")
graph.add_edge("write", END)

app = graph.compile()

2. Conditional Branch (Retry Mechanism): Add a judgment logic after the search node. If the collected search results are too few or the content is insufficient, trigger the re-search operation to improve the quality of raw data.

def should_retry_search(state: ResearchState) -> str:
    results = state.get("search_results", [])
    if not results or len(results[0]) < 100:
        return "search"
    return "analyze"

graph.add_conditional_edges("search", should_retry_search)

4.4 Run the Workflow

Call the compiled graph application, initialize all fields of the state, specify the research topic, and start the task. The whole process of three LLM calls takes about 15 to 20 seconds, and finally outputs a structured research report.

result = app.invoke({
    "topic": "Comparison of open-source LLM inference engines in 2026",
    "search_results": [],
    "analysis": "",
    "report": "",
    "messages": []
})

print(result["report"])

5. Advanced Feature Expansion for Production Environment

5.1 State Persistence (Checkpoint)

In production deployment, tasks may be interrupted due to API exceptions. LangGraph's MemorySaver can realize state recording and breakpoint resume. For formal online projects, replace MemorySaver with SqliteSaver to avoid data loss caused by process restart.

from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()
app = graph.compile(checkpointer=memory)
config = {"configurable": {"thread_id": "research-001"}}

result = app.invoke(
    {"topic": "LangGraph vs AutoGen comparison", "search_results": [], "analysis": [], "report": "", "messages": []},
    config=config
)

When the task is interrupted, use the same thread_id to call again, and the system will automatically skip the completed nodes and resume execution from the breakpoint.

5.2 Human-in-the-Loop Manual Review

Set a pause node before the writing link to realize manual review of analysis results, which is suitable for business scenarios requiring manual audit. After confirming the content, call the interface again to continue the workflow.

app = graph.compile(checkpointer=memory, interrupt_before=["write"])
result = app.invoke(input_data, config=config)
print("Analysis result:", result["analysis"])

# Continue execution after manual confirmation
result = app.invoke(None, config=config)
print("Final report:", result["report"])

6. Summary of Common Development Pitfalls

Combined with actual debugging experience, there are four typical problems that are easy to encounter in the development process, along with targeted solutions:

1. Uninitialized State Fields: If individual fields are not initialized when invoking invoke, subsequent nodes will throw KeyError. The solution is to assign initial values to all fields in the state during invocation.
2. Naming Mismatch of Conditional Edges: The return value of the conditional judgment function must be completely consistent with the node name registered by add_node (case-sensitive). Naming errors will cause the graph to crash during operation.
3. Bloated Message List: Excessively accumulated historical messages will lead to a sharp increase in token consumption. It is recommended to intercept only the latest 5 messages in each agent's prompt.
4. State Conflict of Parallel Nodes: When multiple nodes run in parallel, writing data to the same state field will cause content overwriting. The solution is to divide the fields reasonably and add a dedicated summary node to merge data.

7. Framework Comparison and Selection Suggestions

Combined with the star volume, applicable scenarios and development difficulty of mainstream multi-agent frameworks on GitHub, the following comparative analysis is made:

AutoGen is good at multi-agent dialogue interaction, but the flexibility of process control is insufficient. CrewAI has the lowest entry threshold and can quickly build prototypes by defining roles, but the customization ability for complex processes is weak. Selection suggestions: If the project needs conditional branches, cyclic retries, state persistence and other production-level capabilities, prioritize LangGraph; if it only needs simple dialogue and role collaboration, choose AutoGen or CrewAI to improve development efficiency.

8. Cost Optimization and Subsequent Expansion Directions

The cost of a single complete process using GPT-4o is about 0.05 US dollars. Replacing the model with GPT-4o-mini can reduce the cost to 0.002 US dollars per run, which greatly reduces the long-term operation cost.

For developers who need to frequently call multiple LLMs and Agent frameworks, using a unified API relay service can simplify interface management and control overall costs. As a professional API gateway, 4sapi supports one-stop access to various mainstream large models, and its service price is more favorable than official direct access. It is compatible with mainstream development frameworks, enabling developers to switch models seamlessly without modifying business code.

The system can also be expanded in multiple directions in the follow-up: connecting to real search APIs such as Tavily (providing 1,000 free calls per month); adding a review agent to realize automatic rework of unqualified reports; accessing LangSmith to monitor node time consumption and token usage; and deploying local models such as Llama 3.1 through Ollama to completely save API costs.

9. Conclusion

Building a multi-agent system with LangGraph lowers the technical threshold for AI agent engineering. Through reasonable agent division of labor, standardized state management and flexible graph orchestration, developers can quickly convert simple LLM calling into industrial-grade automated workflows. This 20-minute practical case realizes the full link from demand to online operation, covering core functions and production-level advanced capabilities.

The core difficulty of multi-agent development is not the use of frameworks, but the reasonable design of agent division of labor and communication logic. It is recommended that developers start with simple linear workflows of 2 to 3 agents, and gradually increase the complexity of branches, loops and manual links after running through the basic logic. With the continuous maturity of Agent technology, multi-agent orchestration represented by LangGraph will become the standard configuration of AI engineering development, helping more enterprises realize intelligent upgrading of business processes.