بخش 5.7 · وضعیت، حافظه و پایایی

دستیاری با حافظه و تأییدیه که در برابر ری‌استارت تاب می‌آورد

An assistant with memory and approvals that survives a restart

فهرست مطالب
  1. آنچه در این دمو ساخته می‌شود
  2. کد برنامه
  3. اجرای ثبت‌شده
  4. بررسی نتایج اجرا
  5. تغییرات لازم برای محیط عملیاتی

دستیاری که باید پس از ری‌استارت زنده بماند، به یک چک‌پوینتر (checkpointer) پایدار، یک مخزن (store)، بازبینی به‌ازای هر فراخوانی، تریگر خلاصه‌سازی و یک کلید یکتایی تراکنش (idempotency key) نیاز دارد؛ با این حال، در صورت کرش، تأییدیه باز هم دو بار از بازبین خواسته می‌شود.

دستیار شما پیش از ارسال ایمیل، تأییدیه می‌خواهد. بازبین روی تأیید کلیک می‌کند و لحظه‌ای بعد سرور ری‌استارت می‌شود. آیا ایمیل ارسال شد؟ آیا دستیار دوباره درخواست تأیید می‌کند، یا ایمیل را مجدداً می‌فرستد؟ از طرفی، کاربر انتظار دارد دستیار هفته‌ی بعد و در گفت‌وگویی تازه، مدیرش را به یاد بیاورد.

با پایان این بخش، می‌توانید دستیاری بسازید که رشته‌های گفت‌وگو (threads)، حافظه‌ها و تأییدیه‌های در انتظارش را در میان فرایندها (processes) حفظ کند. همچنین می‌توانید پیش‌بینی کنید که کرش پس از اعمال یک اثر جانبی تأییدشده چه پیامدی دارد و چطور می‌توان آن اثر جانبی را به یک بار اجرا محدود کرد.

آنچه در این دمو ساخته می‌شود

این دمو دستیاری مبتنی بر create_agent با سه ابزار است: remember و recall برای واقعیت‌های مربوط به کاربر، و send_email. هر گام از اجرا در یک فرایند پایتون مجزا انجام می‌شود؛ بنابراین هر ادامه‌ی اجرا (resume) عملاً یک ری‌استارت است. مدل مورد استفاده Qwen3 4B روی Ollama است.

این دمو بخش‌های زیر را به کار می‌گیرد:

کد برنامه

ایجنت هر دو شیء پایداری داده‌ها و دو میان‌افزار را دریافت می‌کند. تریگر خلاصه‌سازی روی 10 پیام تنظیم شده و خلاصه، 4 پیام آخر را نگه می‌دارد:

دستیار capture/demos/assistant/assistant.py
def build(saver, store):
    return create_agent(
        model(),
        tools=[remember, recall, send_email],
        system_prompt=SYSTEM_PROMPT,
        middleware=[
            SummarizationMiddleware(model(), trigger=("messages", 10), keep=("messages", 4)),
            HumanInTheLoopMiddleware(interrupt_on={"send_email": {"allowed_decisions": ["approve", "reject"]}}, interrupt_mode="per_call"),
        ],
        checkpointer=saver,
        store=store,
        context_schema=Context,
    )

ابزارها شناسه‌ی کاربر را از runtime.context می‌خوانند؛ مقداری که کد شما آن را تنظیم می‌کند. مدل نمی‌تواند نام کاربر دیگری را بیاورد و context_schema نوع بافتار را در قالب یک dataclass تعیین می‌کند.

ابزار send_email از tool_call_id خود به‌عنوان کلید یکتایی تراکنش استفاده می‌کند. این کلید، کلید اصلی (primary key) جدول sent است؛ بنابراین درج مجدد با همین کلید هیچ تغییری ایجاد نمی‌کند. هر بار اجرای این ابزار، سطری را هم در attempts می‌نویسد تا در طول اجرا بتوان تعداد دفعات اجرای ابزار را شمرد:

اثر جانبی به همراه کلید آن capture/demos/assistant/assistant.py
@tool
def send_email(to: str, subject: str, body: str, runtime: ToolRuntime[Context]) -> str:
    """Send an email. A person approves each email before it is sent."""
    key = runtime.tool_call_id
    conn = outbox()
    cur = conn.execute("INSERT OR IGNORE INTO sent VALUES (?, ?, ?, ?)", (key, to, subject, body))
    outcome = "sent" if cur.rowcount == 1 else "skipped, key already sent"
    conn.execute("INSERT INTO attempts (idempotency_key, pid, outcome) VALUES (?, ?, ?)", (key, os.getpid(), outcome))
    conn.commit()
    conn.close()
…
    return f"email {outcome}: to {to}, subject {subject!r}"

خطوط print و سوییچ ایجاد کرش در این دمو حذف شده‌اند.

سرویس ایمیل واقعی هم در سمت خودش به چنین بررسی‌ای نیاز دارد. کلید را همراه با درخواست بفرستید تا سرویس بتواند درخواست مجدد با کلیدی را که قبلاً دیده، رد کند.

اجرای ثبت‌شده

اسکریپت run.sh هفت گام را اجرا می‌کند. در گام 1، کاربر دو واقعیت را ارائه می‌دهد و دستیار آن‌ها را ذخیره می‌کند. در گام 2، کاربر درخواست ارسال ایمیل می‌دهد. دستیار ابتدا recall و سپس send_email را فراخوانی می‌کند و اجرا در مرحله‌ی تأیید متوقف می‌شود:

مرحله‌ی 2، تأییدیه در چک‌پوینت منتظر می‌ماند capture/lab/assistant/run.log
== 2-ask-to-send: process 88002, thread t1, durability default, say: Email my manager that the quarterly report is ready.
  call       recall({})
  result     - my manager's email address is lead@example.org - I prefer short replies
  call       send_email({"to": "lead@example.org", "subject": "Quarterly Report Ready", "body": "The quarterly report is ready for review."})
  interrupt  send_email({"to": "lead@example.org", "subject": "Quarterly Report Ready", "body": "The quarterly report is ready for review."}), tool_call_id 3c72b9ba-6b66-47cc-af7a-d11e3338822c
  state      next ['tools'], 9 messages, 18 checkpoints, 1 pending interrupts
  store      2 memories for reader-1
  outbox     0 sent, 0 attempts of send_email
  exit       0

گام 3 فرایند جدیدی است. این فرایند وقفه (interrupt) در انتظار را از فایل می‌خواند، آن را تأیید می‌کند و ایمیل را می‌فرستد. سپس پیش از آنکه LangGraph گام را ذخیره کند، خودش را متوقف می‌کند (kill می‌شود). گام 4 ادامه‌ی اجرای رشته را در فرایند جدید دیگری از سر می‌گیرد:

مراحل 3 و 4، کرش پس از ارسال و سپس ازسرگیری capture/lab/assistant/run.log
== 3-approve-then-crash: process 88024, thread t1, durability default, approve
  reviewer   approve send_email({"to": "lead@example.org", "subject": "Quarterly Report Ready", "body": "The quarterly report is ready for review."})
  tool       send_email ran in this process: sent (key 3c72b9ba-6b66-47cc-af7a-d11e3338822c)
  crash      SIGKILL after the email and before the checkpoint of the tools step
  exit       137

== 4-resume-after-crash: process 88029, thread t1, durability default, resume
  resume     invoke(None) on the thread, next was ['tools']
  interrupt  send_email({"to": "lead@example.org", "subject": "Quarterly Report Ready", "body": "The quarterly report is ready for review."}), tool_call_id 3c72b9ba-6b66-47cc-af7a-d11e3338822c
  state      next ['tools'], 9 messages, 18 checkpoints, 1 pending interrupts
  store      2 memories for reader-1
  outbox     1 sent, 1 attempts of send_email
  exit       0

تأییدیه از بین رفته بود. رشته‌ی گفت‌وگو قبل از گام 3 دارای 18 چک‌پوینت بود و بعد از آن هم 18 چک‌پوینت داشت؛ همان وقفه دوباره با همان tool_call_id منتظر ماند. بازبین درخواستی را برای ایمیلی می‌بیند که هم‌اکنون در صندوق خروجی قرار دارد. گام 5 دوباره تأیید را صادر می‌کند. ابزار برای بار دوم اجرا می‌شود، کلیدش را پیدا می‌کند و از ارسال صرف‌نظر می‌کند:

مرحله‌ی 5، تأییدیه‌ی دوم capture/lab/assistant/run.log
== 5-approve-again: process 88037, thread t1, durability default, approve
  reviewer   approve send_email({"to": "lead@example.org", "subject": "Quarterly Report Ready", "body": "The quarterly report is ready for review."})
  tool       send_email ran in this process: skipped, key already sent (key 3c72b9ba-6b66-47cc-af7a-d11e3338822c)
  result     email skipped, key already sent: to lead@example.org, subject 'Quarterly Report Ready'
  answer     The email was already sent. Let me know if you'd like to take any further action.
  state      next [], 6 messages, 22 checkpoints, 0 pending interrupts
  summary    Here is a summary of the conversation to date: ## SESSION INTENT Send an email to the manager to notify them that the quarterly report is ready. ## SUMMARY - The user’s primary request is to email their manager about the readiness of the quarterly report. - The user has specified a preference for  …
  store      2 memories for reader-1
  outbox     1 sent, 2 attempts of send_email
  exit       0

خط خلاصه در محل علامت‌گذاری‌شده کوتاه شده است.

همین گام خلاصه‌سازی را هم نشان می‌دهد. تعداد پیام‌های رشته از 10 گذشته بود، بنابراین SummarizationMiddleware پیش از فراخوانی مدل، پیام‌های قدیمی را با یک پیام خلاصه جایگزین کرد. وضعیت پس از این گام شامل 6 پیام بود. در گام 6، دستیار آدرس مدیر را مستقیماً از خلاصه‌ و بدون هیچ فراخوانی ابزاری پاسخ داد. در گام 7، رشته‌ی جدید t2 ابزار recall را فراخوانی کرد و هر دو واقعیت را در مخزن یافت. شکل هر فرایند را نشان می‌دهد.

هفت فرایند دستیار، و آنچه هر یک بر جای گذاشتندکرش باعث از دست رفتن مرحله‌ی تأیید شد؛ بنابراین بازبین دوبار تأیید کرد و send_email دوبار اجرا شد، اما کلید مانع شد و صندوق خروجی روی یک ایمیل باقی ماند.
هفت فرایند دستیار، و آنچه هر یک بر جای گذاشتند جدولی با یک سطر برای هر یک از هفت فرایند دستیار اجراشده روی مک، و یک ستون برای هر شمارشی که پس از پایان فرایند ثبت شده است. فرایند 3 ایمیل را تأیید کرد، آن را فرستاد، و با کد خروج 137 متوقف شد. فرایند 4 کار را از سر گرفت و دوباره همان تأییدیه را در انتظار دید. فرایند 5 مجدداً تأیید کرد، send_email برای بار دوم اجرا شد، و بررسی کلید مانع ارسال مجدد گشت. در پایان send_email دو بار اجرا شده بود و صندوق خروجی حاوی 1 ایمیل بود. فرایند 7 روی یک ترد جدید همچنان 2 حافظه در store پیدا کرد. بعدی گره چک‌- پوینت‌ها تأییدیه‌ها در انتظار send_email اجراها ایمیل‌ها ارسال شد 1 یادآوری هیچ 9 0 0 0 2 درخواست ارسال tools 18 1 0 0 3 تأیید SIGKILL، خروج 137: ایمیل ارسال شد، مرحله ذخیره نشد 4 ازسرگیری tools 18 1 1 1 5 تأیید مجدد هیچ 22 0 2 1 6 نوبت سوم هیچ 27 0 2 1 7 ترد جدید t2 هیچ 9 0 2 1 هر سطر یک فرایند جدید پایتون است؛ روی ترد t1 مگر نام دیگری باشد. The counts were read when the process ended. send_email ran twice and one email was sent, because the second run found its tool_call_id in صندوق خروجی. چک‌پوینت‌ها سطرهای همان ترد را در آن سطر می‌شمارند.
هر سطر را به ازای یک فرایند، از بالا به پایین بخوانید. شمارش‌ها هنگام پایان فرایند خوانده شده‌اند. سطر صورتی فرایندی است که متوقف (kill) شد و هیچ وضعیتی بر جای نگذاشت. برگرفته از capture/lab/summary/demos-mac.json.

اجرا با این سطرها در سه فایل به پایان رسید:

صندوق خروجی، چک‌پوینت‌ها و store پس از اجرا capture/lab/assistant/run.log
== files after the run
sent|3c72b9ba-6b66-47cc-af7a-d11e3338822c|lead@example.org|Quarterly Report Ready
attempt|1|3c72b9ba-6b66-47cc-af7a-d11e3338822c|sent
attempt|2|3c72b9ba-6b66-47cc-af7a-d11e3338822c|skipped, key already sent
checkpoints|t1|27
checkpoints|t2|9

بررسی نتایج اجرا

ما دو بار اجرای این هفت گام را روی Mac با تراشه‌ی Apple M1 Max، ده هسته و 64 GiB اندازه گرفتیم. یکی از پایایی پیش‌فرض و دیگری از durability="sync" استفاده کرد. هر اجرا یک آزمایش است؛ بنابراین این شمارش‌ها را صرفاً به‌عنوان یک نمونه بخوانید، نه یک نرخ آماری.

هر دو اجرا در تمامی گام‌ها تعداد یکسانی نشان دادند. در هر دو، تأییدیه پس از کرش باقی نماند. تعداد چک‌پوینت‌ها در گام 3 تغییری نکرد و با ادامه‌ی اجرا، همان وقفه دوباره رخ داد. در هر دو، send_email دو بار اجرا شد و صندوق خروجی یک ایمیل داشت. بخش 5.3 ماتریس ایجنت خود را بدون کلید اجرا کرده بود و این دو اجرا، نخستین آزمون از ایجنتی مجهز به کلید هستند.

گام خلاصه‌سازی در اجرای پیش‌فرض 10.2 ثانیه طول کشید، در حالی که گام 2 معادل 1.4 ثانیه زمان برد. میان‌افزار SummarizationMiddleware خلاصه را با یک فراخوانی مجزا از مدل می‌نویسد و در این اجرا، زمان آن فراخوانی به‌طور جداگانه محاسبه نشد. تأیید در انتظار، مخزن و خلاصه همگی در این دو فایل SQLite ذخیره شدند؛ بنابراین هر فرایند جدید توانست به آن‌ها دسترسی پیدا کند.

دو نتیجه از عملکرد مدل به دست آمد. مدل Qwen3 4B از این قاعده پیروی کرد که پیش از نوشتن، recall را فراخوانی کند و گام 6 را هم از روی خلاصه پاسخ داد. مدلی که recall را نادیده بگیرد، ناچار است آدرس را حدس بزند؛ مرحله‌ی بازبینی دقیقاً همان جایی است که باید جلوی چنین خطایی را گرفت.

تغییرات لازم برای محیط عملیاتی

  • آنچه را که در صندوق خروجی برای کلید فراخوانی ذخیره شده به بازبین نشان دهید تا درخواست دوم پس از کرش واضح باشد.
  • بررسی کلید را علاوه‌بر ابزار خود، در سرویس ارسال‌کننده نیز قرار دهید.
  • مخزن و چک‌پوینتر را در پایگاه داده‌ای نگه دارید که سایر فرایندهای شما هم به آن دسترسی داشته باشند، مانند Postgres.
  • این موضوع را در نظر داشته باشید که فراخوانی مدل خلاصه‌سازی، به زمان نوبت گفت‌وگویی (turn) که تریگر را فعال می‌کند می‌افزاید.

منابع: capture/demos/assistant/assistant.py، capture/demos/assistant/run.sh، capture/demos/assistant/README.md؛ capture/lab/assistant/run.log، capture/lab/assistant/run-sync.log، capture/lab/assistant/run.jsonl، capture/lab/assistant/run-sync.jsonl، capture/lab/summary/demos-mac.json؛ libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py و summarization.py در langchain==1.5.0؛ libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/init.py و libs/checkpoint-sqlite/langgraph/store/sqlite/base.py در langgraph 1.2.22.