Bài 2 — Cài đặt môi trường và dựng graph chạy được đầu tiên

Bài này bạn sẽ có một graph hoàn chỉnh chạy được từ đầu đến cuối, làm bộ khung cho mọi bài sau. Chúng ta đi từ cài đặt, dựng graph tối thiểu, đến cách quan sát state chạy qua từng node.

Chuẩn bị môi trường

• Dùng Python 3.10+ và tạo virtualenv riêng cho dự án để tránh xung đột thư viện.
• Cài thư viện cần thiết:

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install langgraph langchain-openai

• Đặt API key qua biến môi trường, không hard-code trong code:

export OPENAI_API_KEY="sk-..."

• Kiểm tra cài đặt bằng cách import thử: python -c "import langgraph; print('ok')". Nếu in ra ok là bạn đã sẵn sàng.

Dựng graph tối thiểu

Một graph LangGraph luôn gồm 4 phần: định nghĩa State, viết node, khai báo edge, rồi compile thành app chạy được. Ta minh họa bằng một agent viết bài đơn giản: tạo dàn ý rồi viết bản nháp.

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

# 1) State: dữ liệu dùng chung
class State(TypedDict):
    topic: str
    outline: str
    draft: str

# 2) Nodes: mỗi hàm nhận state, trả về phần cập nhật
def make_outline(state: State) -> dict:
    return {"outline": f"Dàn ý cho: {state['topic']}"}

def write_draft(state: State) -> dict:
    return {"draft": f"Bài viết dựa trên {state['outline']}"}

# 3) Graph: thêm node và nối edge
builder = StateGraph(State)
builder.add_node("outline", make_outline)
builder.add_node("draft", write_draft)
builder.add_edge(START, "outline")
builder.add_edge("outline", "draft")
builder.add_edge("draft", END)

# 4) Compile và chạy
app = builder.compile()
result = app.invoke({"topic": "LangGraph cho người mới"})
print(result["draft"])

Chạy file này bạn sẽ thấy draft được điền. START và END là hai node ảo đánh dấu điểm vào/ra của graph — mọi graph đều phải có đường từ START và đến được END.

Hiểu cơ chế cập nhật state

Điểm quan trọng nhất với người mới: node không thay thế toàn bộ state. Nó trả về một dict chỉ chứa các key muốn cập nhật, và LangGraph sẽ merge vào state hiện tại. Vì thế write_draft vẫn đọc được outline mà make_outline đã ghi trước đó, dù bản thân nó không hề trả về outline. Hiểu điều này giúp bạn tránh vô số nhầm lẫn về sau.

Các bước tự kiểm tra graph đầu tiên

• In state đầu ra của invoke để xác nhận từng key được điền đúng.
• Dùng app.get_graph().draw_mermaid() để in sơ đồ Mermaid, kiểm tra luồng khớp thiết kế trên giấy.
• Thử app.stream(input) thay cho invoke để xem state thay đổi sau từng node — cực kỳ hữu ích khi debug.

for step in app.stream({"topic": "demo"}):
    print(step)   # in cập nhật sau mỗi node

Với stream, bạn thấy outline xuất hiện trước, rồi draft — đúng thứ tự thực thi. Đây là cách nhanh nhất để phát hiện node nào không chạy hoặc chạy sai thứ tự.

Checklist "graph khỏe mạnh"

• [ ] Có đúng một đường từ START và đến được END.
• [ ] Mọi node được thêm đều nằm trên một đường đi (không có node mồ côi).
• [ ] Mỗi node trả về dict, không trả về None hay giá trị lạ.
• [ ] Tên key trả về khớp chính xác tên trong State.
• [ ] Chạy stream thấy state tiến triển hợp lý theo thứ tự.

Sai lầm thường gặp

• Quên add_edge(START, ...): graph không biết bắt đầu từ đâu, báo lỗi khi compile.
• Node trả về key sai chính tả: LangGraph vẫn merge nhưng key mong đợi rỗng, gây bug âm thầm. Đối chiếu kỹ với TypedDict.
• Trả về cả object thay vì dict cập nhật: node phải trả {"key": value}, không phải trả nguyên state đã sửa.
• Hard-code API key trong source rồi commit lên git — rủi ro bảo mật nghiêm trọng. Luôn dùng biến môi trường.
• Quên compile: bạn phải gọi builder.compile() để có app; builder chưa chạy được.

Bạn đã có graph chạy đầu-cuối. Bài 3 đi sâu vào thiết kế State — trái tim quyết định độ sạch của toàn bộ agent.