اگر مدل در پرسش ساده خوب جواب می‌دهد اما در کار چندمرحله‌ای مثل «سفارش را پیدا کن، وضعیتش را بگو» گم می‌شود، مشکل معمولاً مدل نیست؛ نبود جریان کنترل‌شده است. در این آموزش LangGraph در پایتون، از نصب نسخه ۱.۲ تا گراف، ابزار، حافظه و کنترل حلقه را با کد قابل اجرا می‌بینید.

آموزش LangGraph در پایتون چه چیزی به شما می‌دهد؟

LangGraph کتابخانه‌ای متن‌باز برای ساخت ایجنت‌های چندمرحله‌ای است که جریان کار را به‌صورت گراف از گره‌ها و یال‌ها تعریف می‌کند. state بین مراحل می‌ماند، ابزارها در حلقه اجرا می‌شوند و مسیر شرطی و تأیید انسانی قابل کنترل است. در ادامه اولین گراف و یک ایجنت ابزارداری را می‌سازید.

فهرست مطالب

LangGraph چیست و چه تفاوتی با زنجیره‌های LangChain دارد؟
پیش‌نیازها و نصب LangGraph
اولین گراف: state، node و edge
ساخت ایجنت ابزارداری با حلقه تصمیم
حافظه و چک‌پوینت؛ ادامه گفتگو بدون فراموشی
مسیر شرطی، چند ایجنت و تأیید انسانی
مقایسه LangGraph با CrewAI و AutoGen
کاربرد واقعی و نکات امنیتی
اشتباهات و خطاهای رایج
سوالات متداول
جمع‌بندی

LangGraph چیست و چه تفاوتی با زنجیره‌های LangChain دارد؟

LangGraph لایه ارکستراسیون است؛ نه مدل زبانی است و نه دیتابیس. در زنجیره خطی، خروجی هر مرحله به مرحله بعد می‌رود و کار تمام می‌شود. در گراف، یک گره می‌تواند دوباره اجرا شود، مسیر بر اساس شرط عوض شود و وضعیت گفتگو در یک state مشترک بماند. همین سه ویژگی، تفاوت یک دمو با ایجنت قابل اتکاست.

چرخه: مدل ابزار را صدا می‌زند، نتیجه را می‌بیند و دوباره تصمیم می‌گیرد.
state مشترک: پیام‌ها با reducer مثل add_messages جمع می‌شوند و هر گره فقط تغییر خودش را برمی‌گرداند.
چک‌پوینت: وضعیت هر گام ذخیره می‌شود؛ گفتگو قابل ادامه و اجرا قابل بازیابی است.

برای پرسش و پاسخ ساده، create_agent از langchain.agents کوتاه‌تر است. LangGraph وقتی ارزش دارد که چرخه، شاخه، چند عامل، حافظه یا تأیید انسانی داشته باشید.

پیش‌نیازها و نصب LangGraph

به پایتون ۳.۱۰ یا بالاتر، کلید API یک ارائه‌دهنده مدل و آشنایی مقدماتی با تایپ‌هینت نیاز دارید. محیط مجازی بسازید تا نسخه‌ها قاطی نشوند:

python -m venv .venv

# ویندوز
.venv\Scripts\activate
# مک و لینوکس
source .venv/bin/activate

pip install "langgraph>=1.2,<2" "langchain>=1,<2" langchain-openai
pip show langgraph

langgraph هسته گراف و چک‌پوینت است، langchain مدل و دکوراتور @tool را می‌دهد و langchain-openai اتصال به OpenAI را. کلید را در متغیر محیطی بگذارید، نه در کد:

# ویندوز (PowerShell)
$env:OPENAI_API_KEY = "sk-..."

# مک و لینوکس
export OPENAI_API_KEY="sk-..."

کلید را هرگز در گیت نگذارید؛ اگر لو رفت، همان لحظه باطلش کنید.

اولین گراف: state، node و edge

هر گراف سه جزء دارد: state (داده مشترک)، node (تابعی که بخشی از state را به‌روز می‌کند) و edge (مسیر حرکت). مثال زیر یک گره پاسخ‌دهنده و شمارنده گام دارد:

from typing import Annotated
from typing_extensions import TypedDict

from langchain.chat_models import init_chat_model
from langchain.messages import AnyMessage
from langgraph.graph import StateGraph, START, END, add_messages

model = init_chat_model("openai:gpt-4o-mini", temperature=0)

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    steps: int

def respond(state: State):
    answer = model.invoke(state["messages"])
    return {"messages": [answer], "steps": state.get("steps", 0) + 1}

builder = StateGraph(State)
builder.add_node("respond", respond)
builder.add_edge(START, "respond")
builder.add_edge("respond", END)

graph = builder.compile()
result = graph.invoke(
    {"messages": [("user", "LangGraph را در یک جمله توضیح بده")]}
)
print(result["messages"][-1].content)
print(result["steps"])

هر گره فقط دیکشنری تغییرات را برمی‌گرداند. add_messages پیام جدید را به تاریخچه اضافه می‌کند، نه اینکه آن را بازنویسی کند. START و END هم مرز اجرا را مشخص می‌کنند.

ساخت ایجنت ابزارداری با حلقه تصمیم

حالا مدل را به ابزار وصل می‌کنیم تا در صورت نیاز آن را صدا بزند، نتیجه را بخواند و دوباره تصمیم بگیرد:

from typing import Literal
from langchain.messages import SystemMessage, ToolMessage
from langchain.tools import tool

SYSTEM = SystemMessage(
    content="تو دستیار فارسی‌زبان فروشگاه هستی. فقط بر اساس نتیجه ابزار پاسخ بده."
)

@tool
def order_status(order_id: str) -> str:
    """وضعیت سفارش را از دیتابیس نمونه برمی‌گرداند."""
    orders = {"A-100": "ارسال شده", "A-200": "در حال بسته‌بندی"}
    return orders.get(order_id, "سفارش پیدا نشد")

tools = [order_status]
tools_by_name = {t.name: t for t in tools}
model_with_tools = model.bind_tools(tools)

def call_model(state: State):
    response = model_with_tools.invoke([SYSTEM] + state["messages"])
    return {"messages": [response], "steps": state.get("steps", 0) + 1}

def call_tools(state: State):
    last = state["messages"][-1]
    results = []
    for call in last.tool_calls:
        output = tools_by_name[call["name"]].invoke(call["args"])
        results.append(
            ToolMessage(content=str(output), tool_call_id=call["id"])
        )
    return {"messages": results}

def route(state: State) -> Literal["tools", "end"]:
    return "tools" if state["messages"][-1].tool_calls else "end"

agent_builder = StateGraph(State)
agent_builder.add_node("agent", call_model)
agent_builder.add_node("tools", call_tools)
agent_builder.add_edge(START, "agent")
agent_builder.add_conditional_edges(
    "agent", route, {"tools": "tools", "end": END}
)
agent_builder.add_edge("tools", "agent")

agent = agent_builder.compile()
result = agent.invoke(
    {"messages": [("user", "وضعیت سفارش A-100 چیست؟")]},
    config={"recursion_limit": 10},
)
print(result["messages"][-1].content)

bind_tools ابزارها را به مدل معرفی می‌کند. اگر مدل قصد فراخوانی داشته باشد، tool_calls پر می‌شود و یال شرطی اجرا را به گره ابزار می‌فرستد. نتیجه در ToolMessage برمی‌گردد و مسیر دوباره به مدل وصل می‌شود. recursion_limit ترمز ایمنی حلقه است.

حافظه و چک‌پوینت؛ ادامه گفتگو بدون فراموشی

تا اینجا هر اجرا از صفر شروع می‌شود. برای گفتگوی چندنوبتی، چک‌پوینتر بدهید و هر گفتگو را با thread_id جدا کنید:

from langgraph.checkpoint.memory import InMemorySaver

chat = agent_builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}

chat.invoke(
    {"messages": [("user", "وضعیت سفارش A-200 چطور است؟")]},
    config=config,
)
chat.invoke(
    {"messages": [("user", "همان سفارش را دوباره توضیح بده")]},
    config=config,
)

snapshot = chat.get_state(config)
print(snapshot.values["messages"][-1].content)

تا وقتی thread_id یکسان بماند، گراف تاریخچه همان گفتگو را می‌بیند. InMemorySaver فقط برای توسعه است و با ری‌استارت پاک می‌شود؛ در تولید از چک‌پوینتر پایدار مانند Postgres استفاده کنید.

مسیر شرطی، چند ایجنت و تأیید انسانی

در پروژه‌های بزرگ‌تر، الگوی «سوپروایزر» رایج است: یک گره تصمیم می‌گیرد کار بعدی را چه کسی انجام دهد و یال‌های شرطی اجرا را به پژوهشگر، نویسنده یا پایان می‌فرستند. هر کارگر می‌تواند زیرگراف مستقل با state و ابزار خودش باشد.

تأیید انسانی: با interrupt قبل از ارسال ایمیل، پرداخت یا حذف داده اجرا را متوقف و منتظر تأیید بمانید.
اجرای موازی: چند شاخه هم‌زمان اجرا و نتیجه در state جمع می‌شود؛ مناسب جستجو در چند منبع.
کنترل هزینه: سقف گام، مدل کوچک برای گره‌های ساده و خلاصه‌سازی تاریخچه.

قبل از افزودن هر عامل جدید بپرسید آیا یک گره و یک ابزار ساده کافی نیست؛ گراف پیچیده بدون نیاز واقعی فقط دیباگ را سخت می‌کند.

مقایسه LangGraph با CrewAI و AutoGen

هر سه برای سیستم‌های چندعاملی‌اند، اما فلسفه متفاوتی دارند. این جدول معیار انتخاب است، نه حکم برنده:

معیار	LangGraph	CrewAI	AutoGen
کنترل جریان	گراف صریح با state، چرخه و شرط	مبتنی بر نقش و تیم	مبتنی بر گفتگوی چندعاملی
شفافیت دیباگ	بالا؛ هر گره قابل رهگیری است	متوسط	متوسط
سرعت شروع	متوسط؛ نیاز به طراحی گراف	بالا	متوسط
مناسب برای	فرایند سازمانی با شرط، حافظه و تأیید انسانی	پروتوتایپ سریع تیم عامل‌ها	پژوهش و همکاری چندعاملی

برای جریان خطی هیچ‌کدام لازم نیست. اگر کنترل دقیق مسیر، بازیابی اجرا و اتصال به سیستم داخلی می‌خواهید، LangGraph دست‌بازتر است. مستندات همان نسخه را بررسی کنید.

کاربرد واقعی و نکات امنیتی

یک سناریوی واقعی: ایجنت پشتیبانی با ابزار سفارش، دانش‌نامه و ارسال تیکت. برای اتصال به مدل از آموزش API اوپن‌ای‌آی در پایتون شروع کنید و بعد همین گراف را با آموزش FastAPI در پایتون به سرویس وب تبدیل کنید.

کمترین دسترسی: ابزار حذف یا پرداخت را بدون تأیید انسانی به مدل ندهید.
اعتبارسنجی ورودی: آرگومان‌هایی مثل شناسه سفارش را قبل از اجرا با Pydantic بررسی کنید.
تزریق پرامپت: نتیجه ابزار را داده بدانید، نه دستور؛ خروجی آن می‌تواند آلوده باشد.
رصد: گام‌ها و تصمیم‌ها را لاگ کنید تا خطا و هزینه قابل ردیابی باشد.

اشتباهات و خطاهای رایج

نبود شرط خروج: حلقه بی‌پایان به GraphRecursionError می‌رسد؛ سقف گام و خروج صریح بگذارید.
مدل بدون tool calling: نتیجه، tool_calls خالی و پاسخ ناقص است؛ مدل سازگار انتخاب کنید.
حذف reducer: بدون add_messages هر گره تاریخچه را بازنویسی می‌کند.
فراموشی thread_id: بدون شناسه ثابت، چک‌پوینتر هر بار گفتگوی جدید می‌سازد.
قاطی کردن sync و async: نود async را با invoke همگام صدا نزنید.

سوالات متداول

آیا LangGraph رایگان است؟

کتابخانه متن‌باز و رایگان است؛ هزینه اصلی مدل، API و زیرساخت است. برای تست می‌توانید از مدل محلی یا اعتبار اولیه استفاده کنید.

برای چت‌بات ساده هم مناسب است؟

برای جریان خطی، create_agent یا زنجیره ساده کافی است. LangGraph وقتی به‌صرفه است که چرخه، شاخه، حافظه پایدار یا تأیید انسانی داشته باشید.

حافظه در تولید چطور پایدار می‌ماند؟

InMemorySaver برای توسعه است. از چک‌پوینتر پایدار مانند Postgres استفاده کنید و برای هر گفتگو thread_id یکتا بسازید.

با مدل‌های محلی مثل Ollama کار می‌کند؟

بله؛ هر مدلی که در LangChain ادغام شده یا رابط سازگار داشته باشد. کیفیت tool calling مدل محلی را قبل از مسیرهای حساس بسنجید.

چطور هزینه را کم کنیم؟

حلقه را محدود کنید، برای گره‌های ساده مدل کوچک بگذارید، تاریخچه را خلاصه و نتیجه‌های تکراری را کش کنید.

جمع‌بندی

LangGraph ابزار کنترل است، نه جادو. با تعریف صریح state، مسیر و خروج، ایجنتی قابل تست می‌سازید. چک‌لیست:

نسخه‌ها را پین و با pip show langgraph بررسی کنید.
state را با add_messages و فیلدهای مشخص بسازید.
شرط خروج و recursion_limit را از ابتدا تعیین کنید.
ابزارها را کم‌دسترسی، اعتبارسنجی‌شده و قابل لاگ نگه دارید.
برای تولید از چک‌پوینتر پایدار و thread_id یکتا استفاده کنید.
هر تغییر گراف را با تست ساده و رصد گام‌ها بررسی کنید.

قدم بعدی؟ یک ابزار واقعی اضافه کنید و مسیر خطا را هم تست کنید؛ همان‌جا تفاوت دمو با ایجنت قابل اتکا مشخص می‌شود.

آموزش LangGraph در پایتون؛ ساخت ایجنت چندمرحله‌ای