هر گره در
StateGraphیک بهروزرسانی جزئی برمیگرداند؛ سپس هر کلید وضعیت یا این تغییر را با کاهندهی (Reducer) خود ادغام (merge) میکند، یا اگر کاهندهای نداشته باشد، مقدار جدید را جایگزین مقدار قبلی میسازد.
گرافی را در نظر بگیرید که در آن سه گره همزمان در یک گام اجرا میشوند و هر کدام جوکی را به یک لیست اضافه میکنند. یک نسخه از این گراف در نهایت با سه جوک به پایان میرسد؛ اما نسخهی دیگر پیش از پایان همان گام با خطا متوقف میشود. عامل تعیینکننده، کاهندهی کلیدی است که گرهها روی آن مینویسند.
پس از پایان این بخش، میتوانید ساختار وضعیت (State schema) را تعریف کنید و برای هر کلید کاهندهی مناسبی برگزینید. همچنین میتوانید رفتار گراف را هنگام دو عملیات نوشتن روی یک کلید در یک گام پیشبینی کنید.
ساختار وضعیت
وضعیت (State): دادههای اشتراکی در یک بار اجرای گراف که در قالب یک ساختار مشخص تعریف میشود؛ کلیدهای این ساختار مقادیری هستند که گرهها میخوانند و مینویسند.
کاهنده (Reducer): تابعی بر حسب مقدار قبلی و مقدار بهروزرسانی که مقدار جدید یک کلید وضعیت را برمیگرداند.
تابع create_agent در بخش 1 گراف را برای شما میساخت. شیء StateGraph دقیقاً همان ساختار است، با این تفاوت که آن را دستی میسازید. کیت وضعیت خود را با TypedDict تعریف میکند؛ دو کلید کاهندهی خود را درون Annotated میآورند و سه کلید دیگر کاهندهای ندارند:
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}}.
گره یک بهروزرسانی جزئی برمیگرداند
هر گره تابعی از وضعیت است و دیکشنریای برمیگرداند که فقط شامل کلیدهای تغییریافته است. نخستین گره در گرافِ کیت، دو کلید از پنج کلید را مینویسد:
def plan(state):
return {"subjects": ["cats", "dogs", "owls"], "log": ["plan"]}کتابخانهی LangGraph هر کلیدِ این بهروزرسانی را با کاهندهی همان کلید اعمال میکند. چون subjects کاهندهای ندارد، لیستِ جدید جایگزین لیست خالیِ ورودی میشود. اما log کاهندهی operator.add دارد؛ در نتیجه ["plan"] به انتهای لیست قبلی ملحق میشود. تمام گرههای بعدی نیز به همین ترتیب یک ورودی به log اضافه میکنند.
در پایان، اجرای گراف با 6 ورودی در log خاتمه مییابد؛ یعنی یک ورودی به ازای اجرای هر گره:
"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 مینویسند:
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")اجرای گراف در پایان گام با خطا متوقف میشود و در متن خطا، نام کلید مشخص است:
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تصویر رفتار این دو کلید را در کنار یکدیگر نشان میدهد.
لیست ادغامشده ترتیب سه موضوع را حفظ میکند: گربهها، سگها، جغدها. آزمونِ کیت در هر بار اجرا این ترتیب را دوباره ثبت میکند.
پیامدهای خطا در رشتهی ذخیرهشده
روی گرافی که چکپوینتر (Checkpointer) دارد، این خطا به چیزی فراتر از شکست همان یک بار اجرا میانجامد. بدنهی هر دو گره پیش از رخداد خطا اجرا شده و هر دو عملیات نوشتن بهصورت تغییرات معلق (Pending writes) ذخیره شدهاند. از این رو، هر بار خواندنِ بعدیِ این رشته (Thread)، همان تغییرات را دوباره اعمال میکند و باز هم با خطا مواجه میشود.
بخش محیط اجرا (Runtime) این گرافِ دوگرهای را همراه با چکپوینتر InMemorySaver اجرا کرد. روی ماشین مهمان در سرور x86، هر گره رقمی را از Qwen3 4B درخواست کرد و آن را در قالب x برگرداند:
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، هر کدام را با یک بار اجرا روی همان گراف آزمایش کردیم:
## 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 را باقی گذاشت:
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).