LangGraph là gì? Hướng dẫn xây dựng tác nhân AI ghi nhớ trạng thái

Hầu hết mã agent bắt đầu đơn giản rồi nhanh chóng khó bảo trì khi phải retry, phân nhánh hoặc chờ con người phê duyệt. Bạn có thể kết nối một LLM với vài tool trong một script tuyến tính, nhưng khi workflow cần “suy luận → hành động → quan sát → suy luận lại”, các câu lệnh if/else sẽ phình to rất nhanh. LangGraph giải quyết vấn đề này bằng cách mô hình hóa agent dưới dạng đồ thị có trạng thái chia sẻ, trong đó vòng lặp và nhánh là thành phần hạng nhất thay vì logic điều khiển rối rắm.

Dùng thử Apidog ngay hôm nay

LangGraph là gì

LangGraph là framework điều phối cấp thấp và runtime để xây dựng các agent có trạng thái, chạy lâu dài. Nó được phát triển bởi LangChain Inc, nhưng là một thư viện riêng với trọng tâm riêng: điều phối workflow agent dạng đồ thị.

Cài đặt:

pip install -U langgraph

Bạn có thể dùng LangGraph độc lập, không bắt buộc phải dùng toàn bộ hệ sinh thái LangChain.

Ý tưởng cốt lõi:

• Node thực hiện công việc: gọi model, gọi tool, xử lý dữ liệu.
• Edge quyết định node nào chạy tiếp theo.
• State là trạng thái chung được truyền qua toàn bộ graph.
• Cycle cho phép workflow quay lại node trước đó để retry, gọi thêm tool hoặc tiếp tục suy luận.

Nếu Chain truyền thống là một chuỗi tuyến tính:

step 1 -> step 2 -> step 3 -> done

thì LangGraph cho phép workflow dạng:

model -> tool -> model -> tool -> model -> done

Đây là mô hình phù hợp hơn với agent thực tế, vì agent thường phải quan sát kết quả tool rồi quyết định bước tiếp theo.

Vấn đề LangGraph giải quyết

Agent workflow thường có tính chu kỳ. Một agent có thể:

1. Nhận yêu cầu từ người dùng.
2. Gọi LLM.
3. LLM yêu cầu gọi tool.
4. Tool trả về kết quả.
5. LLM phân tích kết quả.
6. Tiếp tục gọi tool hoặc kết thúc.

Nếu tự viết bằng script tuyến tính, bạn phải tự xử lý nhiều vấn đề:

• Vòng lặp có điều kiện dừng: tiếp tục gọi tool cho đến khi hoàn thành nhưng không chạy vô hạn.
• Phân nhánh theo trạng thái: điều hướng workflow dựa trên output của model hoặc tool.
• Khả năng phục hồi: tiếp tục từ bước gần nhất sau crash, timeout hoặc restart.
• Human-in-the-loop: tạm dừng để người dùng kiểm tra, chỉnh sửa hoặc phê duyệt.
• Streaming: phát token và trạng thái trung gian khi workflow đang chạy.

LangGraph đưa các khả năng này vào runtime thay vì buộc bạn tự xây dựng một state machine thủ công.

Các khái niệm cốt lõi: State, Node, Edge và Graph

LangGraph xoay quanh bốn khái niệm chính.

1. State

State là object có kiểu dữ liệu dùng chung trong toàn bộ lần chạy. Bạn định nghĩa schema cho state, thường bằng TypedDict.

Ví dụ:

from typing import TypedDict, List

class AgentState(TypedDict):
    messages: List[str]
    step_count: int

LangGraph cũng cung cấp sẵn MessagesState, phù hợp với các agent dạng chat vì nó lưu danh sách message đang chạy.

2. Node

Node là hàm xử lý. Mỗi node nhận state hiện tại và trả về phần cập nhật cho state.

def call_model(state):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

3. Edge

Edge nối các node với nhau.

• add_edge() dùng cho luồng cố định.
• add_conditional_edges() dùng cho routing theo điều kiện.

Ví dụ: nếu model yêu cầu gọi tool thì đi đến node tools, nếu không thì kết thúc.

4. START và END

START và END là marker đặc biệt xác định điểm bắt đầu và kết thúc của graph.

Ví dụ LangGraph tối thiểu

Đây là skeleton cơ bản của một agent có vòng lặp gọi tool:

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)

builder.add_node("model", call_model)
builder.add_node("tools", tool_node)

builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")  # quay lại model sau khi chạy tool

graph = builder.compile()

Điểm quan trọng nằm ở dòng này:

builder.add_edge("tools", "model")

Sau khi tool chạy xong, workflow quay lại model. Model có thể quyết định gọi thêm tool hoặc kết thúc. Đây là vòng lặp agent mà LangGraph được thiết kế để xử lý.

Thêm giới hạn vòng lặp để tránh chạy vô hạn

Trong production, bạn nên thêm giới hạn số bước để tránh agent bị kẹt trong vòng lặp.

Ví dụ state có thêm step_count:

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, START, END

class AgentState(TypedDict):
    messages: list
    step_count: int

MAX_STEPS = 8

def call_model(state: AgentState):
    response = model.invoke(state["messages"])

    return {
        "messages": state["messages"] + [response],
        "step_count": state["step_count"] + 1,
    }

def route_next(state: AgentState) -> str:
    if state["step_count"] >= MAX_STEPS:
        return END

    last = state["messages"][-1]
    return "tools" if getattr(last, "tool_calls", None) else END

Cách này giúp bạn kiểm soát chi phí token và tránh workflow chạy mãi khi model không tìm được điểm dừng.

Khả năng duy trì trạng thái và human-in-the-loop

LangGraph hỗ trợ checkpoint. Khi compile graph với checkpointer, runtime sẽ lưu snapshot state sau mỗi bước.

Ví dụ dùng InMemorySaver khi phát triển:

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())

config = {
    "configurable": {
        "thread_id": "user-42"
    }
}

graph.invoke(
    {"messages": [user_message]},
    config
)

thread_id cho phép LangGraph biết lần chạy nào cần được khôi phục. Trong lần gọi tiếp theo với cùng thread_id, graph có thể tiếp tục từ checkpoint tương ứng.

InMemorySaver phù hợp cho local development. Với môi trường cần sống sót qua restart, bạn nên dùng checkpointer có backend bền vững hơn như SQLite hoặc Postgres.

Checkpoint cũng là nền tảng cho human-in-the-loop:

1. Graph chạy đến một node cần phê duyệt.
2. Runtime lưu state.
3. UI hiển thị state cho người dùng.
4. Người dùng chỉnh sửa hoặc phê duyệt.
5. Graph tiếp tục từ checkpoint đó.

Các flow như “xác nhận trước khi gửi email”, “duyệt trước khi gọi API production” hoặc “cho phép user chỉnh sửa plan” đều có thể xây dựng theo mô hình này.

Streaming trong LangGraph

Với agent chạy nhiều bước, người dùng không nên phải chờ đến cuối mới thấy kết quả. LangGraph có thể stream token và update theo từng node, giúp UI hiển thị tiến trình thực thi.

Mô hình triển khai thường là:

for event in graph.stream(input_state, config):
    print(event)

Bạn có thể dùng stream để hiển thị:

• token từ model,
• node hiện tại đang chạy,
• tool nào vừa được gọi,
• output trung gian,
• trạng thái cuối cùng.

Điều này đặc biệt hữu ích khi agent gọi nhiều API hoặc xử lý tác vụ kéo dài.

LangGraph liên quan đến LangChain như thế nào

LangChain là bộ công cụ rộng hơn: model wrapper, prompt template, retriever, document loader và tích hợp với nhiều nhà cung cấp.

LangGraph là lớp điều phối workflow agent có trạng thái.

Bạn không bắt buộc phải dùng LangChain để dùng LangGraph. Bên trong node, bạn có thể gọi bất kỳ model client nào:

def call_model(state):
    response = openai_client.chat.completions.create(...)
    return {"messages": [response]}

Nhiều team dùng cả hai:

• LangChain để tận dụng model/tool abstraction.
• LangGraph để điều phối vòng lặp, branch, checkpoint và human-in-the-loop.

	LangChain	LangGraph
Vai trò	Thành phần và tích hợp	Điều phối và runtime
Luồng điều khiển	Chuỗi tuyến tính	Đồ thị có nhánh và chu trình
Trạng thái tích hợp	Hạn chế	Chia sẻ, có kiểu dữ liệu, có thể bền vững
Khả năng tiếp tục	Không phải trọng tâm chính	Checkpointer + thread ID
Phù hợp nhất cho	Ghép nối model, prompt, tool	Agent nhiều bước, có trạng thái

Một lưu ý cho người dùng hiện tại: dòng LangGraph v1.0, ổn định từ cuối năm 2025, đã chuyển helper agent dựng sẵn sang langchain.agents.create_agent. Hãy kiểm tra phiên bản đã cài và tài liệu tham khảo chính thức trước khi copy các snippet cũ.

Nếu bạn muốn hiểu cách thiết kế agent từ đầu, xem thêm hướng dẫn về xây dựng một AI agent tùy chỉnh.

LangGraph Platform và Studio

Thư viện mã nguồn mở là phần cốt lõi. Khi cần debug và triển khai, bạn có thể dùng thêm Studio và Platform.

LangGraph Studio

LangGraph Studio là một IDE agent trực quan. Nó hiển thị graph, cho phép chạy workflow và xem state tại từng node.

Với workflow có vòng lặp và conditional routing, nhìn đường đi thực tế của agent thường dễ debug hơn nhiều so với đọc log tuyến tính.

LangGraph Platform

LangGraph Platform là lớp triển khai được quản lý cho agent:

• expose agent dưới dạng API endpoint,
• hỗ trợ persistence cho các lần chạy dài,
• cung cấp tùy chọn self-host hoặc managed cloud.

Bạn không cần Platform để dùng thư viện LangGraph. Nó hữu ích khi bạn muốn triển khai agent production mà không tự xây toàn bộ hạ tầng runtime.

Khi nào nên dùng LangGraph

Dùng LangGraph khi workflow agent có luồng điều khiển thực sự.

Các dấu hiệu phù hợp:

• Agent phải gọi tool, quan sát kết quả rồi quyết định bước tiếp theo.
• Workflow cần branch dựa trên output của model.
• Một lần chạy có thể kéo dài nhiều phút hoặc nhiều giờ.
• Bạn cần resume sau crash hoặc restart.
• Người dùng phải phê duyệt hoặc chỉnh sửa giữa chừng.
• Bạn điều phối nhiều agent hoặc sub-agent dùng chung state.

Không cần dùng LangGraph nếu tác vụ chỉ là:

• một lần gọi model,
• một pipeline tuyến tính ngắn,
• một tác vụ không cần retry, branch hoặc state bền vững.

Ví dụ “tóm tắt đoạn văn này” thường không cần graph. Hãy dùng LangGraph khi cấu trúc workflow thực sự phức tạp.

API testing và mocking nằm ở đâu trong workflow agent

LangGraph điều phối agent, nhưng agent vẫn phụ thuộc vào các API bên dưới:

• API của LLM,
• API của tool,
• API search,
• CRM,
• backend nội bộ,
• service staging hoặc production.

LangGraph không kiểm thử các API này. Đây là phần bạn nên xử lý riêng bằng công cụ như Apidog.

Có hai vấn đề thường gặp khi phát triển LangGraph agent.

1. Gọi API thật trong mỗi lần test rất tốn kém

Nếu mỗi lần chạy graph đều gọi LLM thật hoặc tool thật, bạn sẽ gặp:

• chi phí token tăng,
• rate limit,
• dữ liệu test không ổn định,
• khó tái hiện bug.

Cách xử lý: mock endpoint mà agent phụ thuộc vào.

Bạn có thể giả lập API để tool trả về response cố định trong quá trình phát triển.

Ví dụ node gọi API tool:

import requests

def call_weather_tool(state):
    city = state["city"]

    response = requests.get(
        f"https://mock-api.example.com/weather?city={city}"
    )

    data = response.json()

    return {
        "weather": data
    }

Khi response mock ổn định, bạn có thể test routing logic của graph mà không phụ thuộc vào API thật.

2. Agent dễ hỏng khi schema response thay đổi

Các node thường giả định response có shape cố định.

Ví dụ:

def route_by_status(state):
    status = state["tool_result"]["status"]

    if status == "approved":
        return "execute"
    return "manual_review"

Nếu API đổi status thành state, node này có thể lỗi hoặc route sai.

Bạn nên dùng xác nhận API để kiểm tra:

• status code,
• field bắt buộc,
• kiểu dữ liệu,
• enum hợp lệ,
• response time,
• contract giữa tool và agent.

Nếu muốn quy trình kiểm thử tập trung vào agent, xem thêm bộ công cụ kiểm thử Apidog cho AI agent.

Nói ngắn gọn: LangGraph điều phối agent; Apidog kiểm thử và mock các API mà agent gọi.

Checklist triển khai LangGraph agent

Khi đưa agent vào môi trường thực tế, hãy kiểm tra các mục sau:

• [ ] State schema được định nghĩa rõ ràng.
• [ ] Mỗi node chỉ cập nhật phần state cần thiết.
• [ ] Conditional edge có đường kết thúc (END).
• [ ] Có giới hạn số vòng lặp hoặc số bước.
• [ ] Tool call có timeout.
• [ ] API tool được mock trong dev/test.
• [ ] Response schema của tool được assert.
• [ ] Có checkpointer nếu workflow cần resume.
• [ ] Có thread_id ổn định cho từng conversation hoặc job.
• [ ] Secret/API key không hard-code trong node.
• [ ] Có logging hoặc streaming để debug từng bước.

Các câu hỏi thường gặp

LangGraph có thay thế LangChain không?

Không. LangGraph là runtime điều phối workflow có trạng thái. LangChain là bộ thành phần và tích hợp rộng hơn. Bạn có thể dùng LangGraph độc lập hoặc kết hợp với LangChain.

Tôi có cần biết LangChain để bắt đầu với LangGraph không?

Không. Bạn có thể bắt đầu bằng StateGraph, node, edge và model client bất kỳ. LangChain hữu ích nếu bạn muốn dùng sẵn wrapper cho model, tool hoặc retriever, nhưng không bắt buộc.

LangGraph ghi nhớ trạng thái giữa các lần gọi như thế nào?

Thông qua checkpointer. Khi compile graph với checkpointer và truyền thread_id, LangGraph lưu snapshot state sau mỗi bước và khôi phục lại trong lần gọi tiếp theo với cùng thread.

Làm cách nào để kiểm tra API mà agent gọi?

Hãy kiểm thử và mock API riêng khỏi graph. Mock endpoint LLM hoặc tool để quá trình chạy nhanh, rẻ và ổn định. Đồng thời assert response schema để tránh việc một field thay đổi làm hỏng node hoặc conditional edge. Hướng dẫn kiểm tra ChatGPT API bao gồm xác thực, streaming và tool calling — các bề mặt quan trọng mà agent thường phụ thuộc vào.

Tóm tắt

LangGraph phù hợp khi bạn cần xây agent có vòng lặp, phân nhánh, trạng thái bền vững và khả năng tạm dừng để con người can thiệp. Hãy mô hình hóa workflow dưới dạng graph, dùng state có schema rõ ràng, thêm giới hạn vòng lặp và bật checkpoint khi cần resume.

LangGraph xử lý phần điều phối. Các API mà agent gọi vẫn cần được mock, test và assert contract riêng. Bạn có thể dùng Apidog để giả lập endpoint, xác nhận response và giảm chi phí phát triển trước khi agent gọi API thật. Tải xuống Apidog để bắt đầu mock một endpoint và kiểm tra response của nó trong workflow agent.