State در LangGraph چیست و چه مشکلی را حل میکند؟
مدلهای زبانی ذاتاً بیحافظهاند: هر درخواست به chat/completions مستقل است و اگر تاریخچه را دوباره نفرستید، مدل چیزی از نوبتهای قبلی نمیداند. حالا یک agent را تصور کنید که باید چند نود را پشت سر هم اجرا کند — یکی درخواست کاربر را تحلیل میکند، یکی ابزار صدا میزند و یکی پاسخ نهایی را مینویسد. این نودها به یک جای مشترک نیاز دارند تا نتایج کارشان را در آن بگذارند و نود بعدی از همان بخواند. در LangGraph این جای مشترک «State» نام دارد و درست بودن طراحی آن، تفاوت میان یک agent قابل اعتماد و یک دموی شکننده است.
State در LangGraph یک شیء جادویی نیست؛ یک ساختار دادهٔ ساده و کاملاً قابل پیشبینی است که اسکیمایش را خودتان تعریف میکنید. در این مقاله از یک TypedDict ساده شروع میکنیم، reducer و add_messages را اضافه میکنیم، خطای InvalidUpdateError را دیباگ میکنیم و در پایان با checkpointer و thread_id چتباتی میسازیم که نام شما را در invoke دوم به یاد میآورد — با اتصال واقعی به مدلهای APX24 از طریق endpoint سازگار با OpenAI. تمام کدها قابل copy-paste و اجرا هستند.
- تعریف Graph State و مفهوم channel و superstep در مدل اجرای LangGraph
- بهروزرسانی State: overwrite پیشفرض در برابر reducerهای Annotated
- add_messages و MessagesState برای مدیریت تاریخچهٔ گفتگو
- persistence با InMemorySaver و thread_id بین چند فراخوانی
- دیباگ InvalidUpdateError و دو خطای رایج دیگر State
- انتخاب مدل APX24 برای نودهای گراف بر اساس نقش و هزینهٔ توکن
تشبیه ملموس: State مثل وایتبرد اتاق کنترل
این تشبیه دقیقاً همان چیزی است که مستندات رسمی با مفاهیم channel و superstep توصیف میکنند: هر کلید State یک کانال مستقل است و برنامه در گامهای مجزا پیش میرود. طبق مستندات رسمی LangGraph، این مدل اجرا از سیستم Pregel گوگل الهام گرفته شده است. این نکته فقط اطلاعات تاریخی نیست؛ وقتی در بخش بعدی دیدیم که دو نود موازی چطور ادغام میشوند، ریشهٔ همان تصمیمها در مدل superstep است.
تعریف دقیق: Graph State چیست و چطور تعریف میشود؟
برای تعریف اسکیما سه راه دارید: TypedDict که سبکترین و رایجترین است، dataclass و Pydantic BaseModel. Pydantic زمانی بهترین انتخاب است که اعتبارسنجی سختگیرانهٔ ورودی میخواهید؛ مستندات رسمی هر سه را پشتیبانی میکنند. ما در این مقاله با TypedDict پیش میرویم چون خواناترین شروع است و تمرکز را روی مفهوم نگه میدهد، نه روی کتابخانهٔ اعتبارسنجی. نکتهٔ مهم: در هر سه حالت، reducerها با Annotated تعریف میشوند و رفتار ادغام یکسان است.
دقت کنید نود step هیچوقت هم count و هم history را برنمیگرداند؛ این «بهروزرسانی جزئی» قلب طراحی LangGraph است و دو مزیت بزرگ دارد: نودها مستقل و قابل تست واحد میشوند، و تغییر اسکیمای State در آینده فقط نودهای مرتبط با آن کلید را تحت تأثیر قرار میدهد. همین اصل، نگهداری گرافهای بزرگ با دهها نود را ممکن میکند.
LangGraph چطور State را بهروزرسانی میکند؟ (چرخهٔ superstep)
- 1
ورودی اولیه
graph.invoke({'messages': [...]}) مقدار اولیهٔ هر کلید State را تعیین میکند.
- 2
اجرای superstep
LangGraph در هر superstep همهٔ نودهای فعال آن گام را اجرا میکند — طبق مستندات رسمی، الهام از Pregel گوگل.
- 3
بازگرداندن بهروزرسانی جزئی
هر نود یک dict کوچک شامل فقط کلیدهایی که میخواهد تغییر دهد برمیگرداند.
- 4
اعمال reducer
برای هر کلید بهروزرسانیشده، LangGraph تابع reducer آن کلید را صدا میزند؛ بدون reducer، مقدار جدید جایگزین میشود.
- 5
snapshot در checkpointer
اگر checkpointer تنظیم شده باشد، وضعیت بعد از هر superstep بهعنوان checkpoint ذخیره میشود.
- 6
ادامه یا پایان
بر اساس یالها و conditional edges، superstep بعدی اجرا یا گراف با END تمام میشود.
دو نتیجهٔ عملی مستقیماً از این مدل بیرون میآید. اول: دو نود موازی هر دو نسخهٔ قبل از خودشان را میبینند و بهروزرسانیشان بعداً ادغام میشود — پس نتیجه به ترتیب اجرای داخلی وابسته نیست، به reducer وابسته است. دوم: اگر هر دو نود یک کلید بدون reducer را بهروزرسانی کنند، LangGraph نمیداند کدام را بپذیرد و خطای InvalidUpdateError میدهد؛ در بخش دیباگ کامل به آن میپردازیم.
Reducer چیست و چه زمانی از add_messages استفاده کنیم؟
reducer یک تابع ساده با امضای (current, update) -> new است. دو reducer آمادهٔ پرکاربرد دارید: operator.add که دو لیست را الحاق میکند و add_messages که مخصوص پیامهای گفتگوست. add_messages هوشمندتر است: پیامهای جدید را اضافه میکند و اگر پیامی با id تکراری برسد، همان پیام را بهروزرسانی میکند — رفتاری که برای ویرایش و حذف پیامها لازم است. هر دو را میتوانید با Annotated به هر کلید لیستی وصل کنید.
مثال حلشده: چتبات stateful با add_messages و APX24
پشتصحنه: درخواست HTTP که نود assistant میزند
زیر پوستهٔ ChatOpenAI چه خبر است؟ هر بار که نود assistant اجرا میشود، یک درخواست POST به /v1/chat/completions زده میشود و آرایهٔ messages آن بدنه دقیقاً از state['messages'] ساخته میشود. دیدن همین درخواست در قالب curl دو چیز را شفاف میکند: اول اینکه مدل هیچ حافظهٔ مستقلی ندارد و همهچیز از State میآید؛ دوم اینکه اندازهٔ State مستقیماً با تعداد توکنهای صورتحساب شما رابطهٔ خطی دارد.
ماندگاری State بین فراخوانیها: Checkpointer و thread_id
تا اینجا State فقط در طول یک invoke زندگی میکرد. برای ماندگاری، LangGraph لایهٔ persistence دارد: checkpointer بعد از هر superstep یک checkpoint از کل State ذخیره میکند و با thread_id مشخص میکنید کدام گفتگو را ادامه میدهید. به thread مثل شناسهٔ فایل گفتگو در یک مسنجر فکر کنید: هر thread تاریخچهٔ مستقل خودش را دارد و کاربر جدید یعنی thread جدید. طبق مستندات رسمی، همین لایه پایهٔ ویژگیهایی مثل human-in-the-loop و time-travel هم هست.
- InMemorySaver (نام قدیمی: MemorySaver) — از langgraph.checkpoint.memory؛ فقط برای تست و توسعه؛ با restart فرایند از بین میرود
- SqliteSaver — پکیج langgraph-checkpoint-sqlite؛ ذخیره روی فایل؛ مناسب پروژههای کوچک و اپلیکیشن دسکتاپ
- PostgresSaver / AsyncPostgresSaver — پکیج langgraph-checkpoint-postgres؛ انتخاب production با پشتیبانی async
- بدون checkpointer — State فقط در طول یک invoke زندگی میکند و بین فراخوانیها چیزی نمیماند
دیباگ: InvalidUpdateError و خطاهای رایج State
ترکیب این دو سناریو تقریباً همهٔ باگهای State را پوشش میدهد: خطاهای بلندگو (runtime error) از خروجی نامعتبر نودها میآیند و خطاهای خاموش از reducerهای جاافتاده. ابزار تشخیص مشترک هر دو هم همان stream_mode='updates' است که در بخش قبل معرفی کردیم — بهروزرسانی هر نود را ببینید و با انتظارتان مقایسه کنید.
انتخاب مدل APX24 برای نودهای گراف: مقایسه و هزینه
یکی از بزرگترین مزیتهای معماری گراف این است که هر نود میتواند مدل خودش را داشته باشد — برخلاف زنجیرههای تکمدلی. قاعدهٔ انتخاب ساده است: نودهای ساده مثل طبقهبندی intent، استخراج فیلد و فرمتدهی با مدلهای اقتصادی هم کیفیت کافی دارند؛ نودهای استدلالی مثل برنامهریزی چندمرحلهای و تحلیل پیچیده مدل قویتر میخواهند. تحلیل زیر بر اساس تجربهٔ تحریریه است و تصمیم نهایی همیشه باید با benchmark روی دادهٔ واقعی پروژهٔ خودتان گرفته شود.
کاربردهای واقعی و مسیر ادامهٔ یادگیری
الگوی سومی هم ارزش دانستن است: گردشکارهای تأیید انسانی. در agentهای حساس (مثلاً صدور بازپرداخت)، نود نهایی قبل از اجرا روی State یک کلید «در انتظار تأیید» مینویسد و اجرا متوقف میشود؛ تأیید انسانی با resume ادامه پیدا میکند. ابزار رسمی این الگو interrupt و Command هستند که موضوع کامل یکی از مقالههای بعدی خوشه است — پایهٔ آن همان چیزی است که اینجا یاد گرفتید.
- Checkpointerهای دائمی: SqliteSaver و PostgresSaver و بازیابی snapshot در production
- Subgraphها: اشتراک State بین چند گراف و الگوهای استاندارد آن
- Human-in-the-loop: توقف و ادامهٔ گراف با interrupt و Command
- Streaming خروجی نودها برای رابطهای کاربری زنده




