بخش 6.1 · جریان کنترل در LangGraph

گراف وضعیت (StateGraph)، وضعیت و کاهنده‌ها (Reducers)

StateGraph, state, and reducers

فهرست مطالب
  1. ساختار وضعیت
  2. گره یک به‌روزرسانی جزئی برمی‌گرداند
  3. دو عملیات نوشتن روی یک کلید در یک گام
  4. پیامدهای خطا در رشته‌ی ذخیره‌شده
  5. بازیابی رشته
  6. تابع add_messages و ساختار MessagesState
  7. پاک‌سازی کلید دارای کاهنده

هر گره در StateGraph یک به‌روزرسانی جزئی برمی‌گرداند؛ سپس هر کلید وضعیت یا این تغییر را با کاهنده‌ی (Reducer) خود ادغام (merge) می‌کند، یا اگر کاهنده‌ای نداشته باشد، مقدار جدید را جایگزین مقدار قبلی می‌سازد.

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

پس از پایان این بخش، می‌توانید ساختار وضعیت (State schema) را تعریف کنید و برای هر کلید کاهنده‌ی مناسبی برگزینید. همچنین می‌توانید رفتار گراف را هنگام دو عملیات نوشتن روی یک کلید در یک گام پیش‌بینی کنید.

ساختار وضعیت

وضعیت (State): داده‌های اشتراکی در یک بار اجرای گراف که در قالب یک ساختار مشخص تعریف می‌شود؛ کلیدهای این ساختار مقادیری هستند که گره‌ها می‌خوانند و می‌نویسند.

کاهنده (Reducer): تابعی بر حسب مقدار قبلی و مقدار به‌روزرسانی که مقدار جدید یک کلید وضعیت را برمی‌گرداند.

تابع create_agent در بخش 1 گراف را برای شما می‌ساخت. شیء StateGraph دقیقاً همان ساختار است، با این تفاوت که آن را دستی می‌سازید. کیت وضعیت خود را با TypedDict تعریف می‌کند؛ دو کلید کاهنده‌ی خود را درون Annotated می‌آورند و سه کلید دیگر کاهنده‌ای ندارند:

یک اسکیمای وضعیت با دو کاهنده capture/s_graph.py
class Fanout(TypedDict):
    topic: str
    subjects: list[str]
    jokes: Annotated[list[str], operator.add]
    log: Annotated[list[str], operator.add]
    best: str

کلیدی که کاهنده ندارد، همیشه آخرین مقدار نوشته‌شده را نگه می‌دارد. صفحه‌ی مستندات API گراف نیز این رفتار پیش‌فرض را تأیید می‌کند و می‌افزاید که هر گره تنها کلیدهایی را که تغییر می‌دهد برمی‌گرداند {{docs oss/python/langgraph/graph-api}}. کتابخانه‌ی LangGraph چنین کلیدی را در یک کانال LastValue ذخیره می‌کند، و کلید دارای کاهنده را در کانال BinaryOperatorAggregate نگه می‌دارد {{docs oss/python/langgraph/pregel}}. ساختار وضعیت می‌تواند یک dataclass یا مدل Pydantic هم باشد، اما create_agent به TypedDict نیاز دارد {{docs oss/python/langgraph/graph-api}}.

گره یک به‌روزرسانی جزئی برمی‌گرداند

هر گره تابعی از وضعیت است و دیکشنری‌ای برمی‌گرداند که فقط شامل کلیدهای تغییریافته است. نخستین گره در گرافِ کیت، دو کلید از پنج کلید را می‌نویسد:

گره برنامه‌ریزی (plan) capture/s_graph.py
    def plan(state):
        return {"subjects": ["cats", "dogs", "owls"], "log": ["plan"]}

کتابخانه‌ی LangGraph هر کلیدِ این به‌روزرسانی را با کاهنده‌ی همان کلید اعمال می‌کند. چون subjects کاهنده‌ای ندارد، لیستِ جدید جایگزین لیست خالیِ ورودی می‌شود. اما log کاهنده‌ی operator.add دارد؛ در نتیجه ["plan"] به انتهای لیست قبلی ملحق می‌شود. تمام گره‌های بعدی نیز به همین ترتیب یک ورودی به log اضافه می‌کنند.

در پایان، اجرای گراف با 6 ورودی در log خاتمه می‌یابد؛ یعنی یک ورودی به ازای اجرای هر گره:

وضعیت نهایی اجرا capture/out/34-stategraph-reducers-send-command.txt
  "jokes": [
    "a joke about cats",
    "a joke about dogs",
    "a joke about owls"
  ],
  "log": [
    "plan",
    "write_joke(cats)",
    "write_joke(dogs)",
    "write_joke(owls)",
    "pick -> publish",
    "publish"
  ],
  "best": "a joke about cats"

وضعیت نهایی. کلیدهای topic و subjects کوتاه‌سازی شده‌اند.

دو عملیات نوشتن روی یک کلید در یک گام

سه اجرای write_joke همگی در یک گام رخ می‌دهند و هر کدام یک جوک ذیل کلید jokes برمی‌گردانند. کاهنده این سه به‌روزرسانی را ادغام می‌کند؛ بنابراین وضعیتْ هر سه جوک را در خود نگه می‌دارد. بخش 6.2 نشان می‌دهد گراف چگونه سه اجرای هم‌زمان از یک گره را شروع می‌کند.

کلیدی که کاهنده ندارد، در هر گام تنها یک بار نوشتن را می‌پذیرد. کیت گرافی می‌سازد که هر دو گره‌ی آن پس از __start__ اجرا می‌شوند و هر دو روی کلید value می‌نویسند:

دو گره روی یک کلید بدون کاهنده می‌نویسند capture/s_graph.py
    class Plain(TypedDict):
        value: str

    g = StateGraph(Plain)
    g.add_node("a", lambda s: {"value": "a"})
    g.add_node("b", lambda s: {"value": "b"})
    g.add_edge(START, "a")
    g.add_edge(START, "b")

اجرای گراف در پایان گام با خطا متوقف می‌شود و در متن خطا، نام کلید مشخص است:

خطای ناشی از دو بار نوشتن روی یک کلید capture/out/34-stategraph-reducers-send-command.txt
raised langgraph.errors.InvalidUpdateError: At key 'value': Can receive only one value per step. Use an Annotated key to handle multiple values.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/INVALID_CONCURRENT_GRAPH_UPDATE

تصویر رفتار این دو کلید را در کنار یکدیگر نشان می‌دهد.

دو بار نوشتن روی یک کلید در یک گامسه بار نوشتن روی کلیدی با operator.add در یک لیست ادغام می‌شوند، و دو بار نوشتن روی کلیدِ بدون کاهنده در پایان گام خطای InvalidUpdateError می‌دهد.
دو بار نوشتن روی یک کلید در یک گام دو ستون. در سمت چپ، سه وظیفه write_joke در یک گام هرکدام یک جوک در کلید jokes (با کاهنده operator.add) می‌نویسند و وضعیت نهایی شامل سه جوک درباره گربه، سگ و جغد می‌شود. در سمت راست، گره‌های a و b هر دو روی کلید value (بدون کاهنده) می‌نویسند و اجرای برنامه با خطای InvalidUpdateError روی کلید value متوقف می‌شود زیرا کلید در هر گام فقط یک مقدار می‌پذیرد. JOKES، کاهنده OPERATOR.ADD VALUE، بدون کاهنده write_joke jokes: [cats] write_joke jokes: [dogs] write_joke jokes: [owls] operator.add سه به‌روزرسانی را در یک گام ادغام می‌کند وضعیت: jokes، 3 مورد یک جوک درباره گربه‌ها یک جوک درباره سگ‌ها، یک جوک درباره جغدها گره a value: "a" گره b value: "b" بدون کاهنده LastValue فقط یک نوشتن در هر گام می‌پذیرد InvalidUpdateError در کلید 'value': در هر گام فقط یک مقدار می‌تواند دریافت کند. دو گراف، هر کدام با نوشتن هم‌زمان روی یک کلید در یک گام. یک کلید دارای کاهنده است.
هر ستون را از بالا (نوشتن‌ها) به پایین (وضعیت) بخوانید. ستون چپ مربوط به jokes در گراف جوک است، و ستون راست مربوط به value در گراف دو-گره‌ای است. برگرفته از capture/out/34-stategraph-reducers-send-command.txt.

لیست ادغام‌شده ترتیب سه موضوع را حفظ می‌کند: گربه‌ها، سگ‌ها، جغدها. آزمونِ کیت در هر بار اجرا این ترتیب را دوباره ثبت می‌کند.

پیامدهای خطا در رشته‌ی ذخیره‌شده

روی گرافی که چک‌پوینتر (Checkpointer) دارد، این خطا به چیزی فراتر از شکست همان یک بار اجرا می‌انجامد. بدنه‌ی هر دو گره پیش از رخداد خطا اجرا شده و هر دو عملیات نوشتن به‌صورت تغییرات معلق (Pending writes) ذخیره شده‌اند. از این رو، هر بار خواندنِ بعدیِ این رشته (Thread)، همان تغییرات را دوباره اعمال می‌کند و باز هم با خطا مواجه می‌شود.

بخش محیط اجرا (Runtime) این گرافِ دوگره‌ای را همراه با چک‌پوینتر InMemorySaver اجرا کرد. روی ماشین مهمان در سرور x86، هر گره رقمی را از Qwen3 4B درخواست کرد و آن را در قالب x برگرداند:

رشته پس از تداخل capture/lab/internals/02-channels/trace.txt
raised InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple values.
…
node bodies that ran before the raise: ['a', 'b']
…
get_state after the raise ALSO raises InvalidUpdateError via ['main.py:1496', 'main.py:1331', '_algo.py:319', 'last_value.py:64']
…
raw saver.get_tuple works: checkpoint step=0 pending_writes=[('26351ed0', 'x', 1), ('8f6a50fe', 'x', 2)]
…
invoke(None) resume raises again: InvalidUpdateError; node bodies re-run on resume: [] (empty means the saved writes were reapplied, not re-executed)

لیست فریم‌ها و خروجی مربوط به هر چک‌پوینت کوتاه‌سازی شده‌اند.

بنابراین get_state با خطا متوقف می‌شود و پنل مدیریتی هم اگر این رشته را بخواند با شکست روبه‌رو می‌شود. فراخوانی invoke(None) بدون اجرای گره‌ها خطا می‌دهد. یک نوبت گفت‌وگوی جدید (Turn) روی همین رشته نیز خطا ایجاد می‌کند. در این وضعیت، تنها get_state_history و خود ذخیره‌ساز به‌صورت خام می‌توانند رشته را بخوانند. ما این مورد را در قالب گزارش اشکال شماره‌ی 9712 در گیت‌هاب LangGraph ثبت کردیم {{issue langgraph#9712}}. بخش 2.2 رخداد این خطا را در فاز به‌روزرسانی بررسی می‌کند.

بازیابی رشته

ما 4 راهکار را روی ماشین مهمان در سرور x86 با مدل Qwen3 4B، هر کدام را با یک بار اجرا روی همان گراف آزمایش کردیم:

دو روش اول از چهار روش رفع تداخل LastValue capture/lab/internals/02-channels/repair.txt
## 1. same graph, after the raise
get_state: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
update_state(cfg, {'x': 9}): ok -> {'configurable': {'thread_id': 't1', 'checkpoint_ns': '', …
invoke(None): raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v
node bodies run by invoke(None): ['a', 'b']; model calls so far 4
invoke({'x': 5}) as a new turn: raises InvalidUpdateError: At key 'x': Can receive only one value per step. Use an Annotated key to handle multiple v

## 2. same saver, graph recompiled with x: Annotated[int, operator.add]
get_state: ok -> {'x': 3}
invoke(None): ok -> {'x': 3}
node bodies run by invoke(None): []; model calls so far 8

شناسه چک‌پوینت در نتیجه update_state کوتاه‌سازی شده و بخش‌های 3 و 4 نیز حذف شده‌اند.

  • تعریف کاهنده، رشته را بر اساس تغییرات ذخیره‌شده‌اش ترمیم می‌کند. همان ذخیره‌ساز، ذیل گرافی با x: Annotated[int, operator.add]، رشته را بلافاصله خواند و اجرا را به پایان رساند. هیچ گره‌ای دوباره اجرا نشد؛ بنابراین هزینه‌ی مضاعفی برای فراخوانی مدل پرداخت نشد. مقدار نهایی 3 بود؛ یعنی مقدار ورودی 0 به‌علاوه‌ی 1 و 2.
  • دستور update_state نیز رشته را بازیابی می‌کند. این دستور یک چک‌پوینت جدید با مقداری که به آن می‌دهید ثبت می‌کند، و کد بازتولید اشکال 9712 پس از آن رشته را دوباره می‌خواند. با این حال، گراف همچنان مشکل دارد؛ فراخوانی بعدیِ invoke(None) هر دو گره و هر دو فراخوانی مدل را دوباره اجرا کرد و باز هم با خطا متوقف شد.
  • ایجاد یک fork از چک‌پوینت ورودی در همان گراف، هر دو گره را دوباره اجرا کرد و متوقف شد.
  • دستور delete_thread رشته را پاک می‌کند و تاریخچه‌اش از دست می‌رود.

بنابراین ابتدا کاهنده را مستقر کنید. با این کار، هر رشته‌ی خراب بر اساس تغییرات ذخیره‌شده‌اش کار را تمام می‌کند. از update_state زمانی استفاده کنید که باید مقدار را دستی تنظیم کنید، آن هم فقط روی گرافی که کاهنده دارد. کاهنده را بر اساس مفهوم کلید انتخاب کنید؛ زیرا همان است که مقدار رشته‌ی تعمیرشده را تعیین می‌کند.

تابع add_messages و ساختار MessagesState

add_messages: کاهنده‌ای برای لیستی از پیام‌ها. این تابع پیامی با شناسه‌ی جدید را اضافه می‌کند، پیامی با شناسه‌ی یکسان را جایگزین نمونه‌ی قبلی می‌سازد و پیامی را که شیء RemoveMessage مشخص کرده باشد حذف می‌کند.

کیت آموزشی تابع add_messages را روی دو پیام m1 و m2 فراخوانی می‌کند. به‌روزرسانی با متنی تازه برای m2 و یک پیام جدید m3، یکی را جایگزین کرد و دیگری را به انتها افزود. ارسال به‌روزرسانی با RemoveMessage(id="m1") نیز فقط m2 را باقی گذاشت:

تابع add_messages بر اساس id جایگزین و حذف می‌کند capture/out/34-stategraph-reducers-send-command.txt
replace m2, append m3:
…
    "content": "first",
    "id": "m1"
…
    "content": "second, edited",
    "id": "m2"
…
    "content": "third",
    "id": "m3"
…
remove m1:
[
  {
    "type": "HumanMessage",
    "content": "second",
    "id": "m2"
  }
]

نتیجه اول به سه شناسه و متن آن خلاصه شده است.

بنابراین کلید messages در یک ایجنت (Agent) می‌تواند درجا تغییر کند. صفحه‌ی مستندات ایجنت‌ها این کلید را صرفاً افزودنی (Append-only) می‌نامد {{docs oss/python/langchain/agents}}، و صفحه‌ی حافظه‌ی کوتاه‌مدت حذف پیام‌ها را با RemoveMessage مستند کرده است {{docs oss/python/langchain/short-term-memory}}. کدِ add_messages تعیین‌کننده‌ی رفتار نهایی است و این راهنما این مغایرت را با عنوان تعارض D104 ثبت می‌کند.

ساختار MessagesState یک ساختار وضعیت با تنها یک کلید messages و کاهنده‌ی add_messages است. هر گره می‌تواند دیکشنری‌ای مانند {"role": "assistant", "content": "..."} برگرداند، و کاهنده آن را به یک AIMessage با شناسه‌ی یکتای جدید (UUID) تبدیل می‌کند. بدین ترتیب تک‌تک پیام‌های وضعیت دارای شناسه می‌شوند تا در به‌روزرسانی‌های بعدی بتوان آن‌ها را تغییر داد یا حذف کرد.

پاک‌سازی کلید دارای کاهنده

گره‌ای که برای کلید log یک لیست خالی برمی‌گرداند آن را پاک نمی‌کند؛ زیرا operator.add لیست خالی را به انتهای لیست قبلی می‌افزاید. صفحه‌ی وضعیت می‌گوید برای نادیده‌گرفتن کاهنده، مقدار را درون Overwrite بپیچید {{docs oss/python/langgraph/graph-api-state}}. کیت هنوز Overwrite را اجرا نمی‌کند. خروجی و بررسی عملی آن در ویرایش بعدی به همراه سایر مباحث باز در بخش 8.8 ارائه خواهد شد.

منابع: capture/s_graph.py، capture/out/34-stategraph-reducers-send-command.txt؛ capture/lab/internals/02-channels/trace.txt، capture/lab/internals/02-channels/run.py، capture/lab/internals/02-channels/repair.txt، capture/lab/internals/02-channels/repair.py؛ libs/langgraph/langgraph/graph/state.py، libs/langgraph/langgraph/graph/message.py، libs/langgraph/langgraph/channels/last_value.py، libs/langgraph/langgraph/pregel/_algo.py و libs/langgraph/langgraph/pregel/main.py در نسخه‌ی langgraph 1.2.22؛ گزارش مشکل گیت‌هاب langchain-ai/langgraph#9712؛ وب‌سایت docs.langchain.com در docs commit 04d4d4a (oss/python/langgraph/graph-api، oss/python/langgraph/graph-api-state، oss/python/langgraph/pregel، oss/python/langchain/agents، oss/python/langchain/short-term-memory).

ترجمه‌ی فارسی StateGraph, state, and reducers از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما