دستیاری که باید پس از ریاستارت زنده بماند، به یک چکپوینتر (checkpointer) پایدار، یک مخزن (store)، بازبینی بهازای هر فراخوانی، تریگر خلاصهسازی و یک کلید یکتایی تراکنش (idempotency key) نیاز دارد؛ با این حال، در صورت کرش، تأییدیه باز هم دو بار از بازبین خواسته میشود.
دستیار شما پیش از ارسال ایمیل، تأییدیه میخواهد. بازبین روی تأیید کلیک میکند و لحظهای بعد سرور ریاستارت میشود. آیا ایمیل ارسال شد؟ آیا دستیار دوباره درخواست تأیید میکند، یا ایمیل را مجدداً میفرستد؟ از طرفی، کاربر انتظار دارد دستیار هفتهی بعد و در گفتوگویی تازه، مدیرش را به یاد بیاورد.
با پایان این بخش، میتوانید دستیاری بسازید که رشتههای گفتوگو (threads)، حافظهها و تأییدیههای در انتظارش را در میان فرایندها (processes) حفظ کند. همچنین میتوانید پیشبینی کنید که کرش پس از اعمال یک اثر جانبی تأییدشده چه پیامدی دارد و چطور میتوان آن اثر جانبی را به یک بار اجرا محدود کرد.
آنچه در این دمو ساخته میشود
این دمو دستیاری مبتنی بر create_agent با سه ابزار است: remember و recall برای واقعیتهای مربوط به کاربر، و send_email. هر گام از اجرا در یک فرایند پایتون مجزا انجام میشود؛ بنابراین هر ادامهی اجرا (resume) عملاً یک ریاستارت است. مدل مورد استفاده Qwen3 4B روی Ollama است.
این دمو بخشهای زیر را به کار میگیرد:
- چکپوینترها و رشتههای گفتوگو:
SqliteSaverهر رشته را در یک فایل ذخیره میکند. - حالتهای پایایی، و کرش بین دو گام: کرش و کلید یکتایی تراکنش.
- مخازن و حافظهی بلندمدت:
SqliteStore، با شناسهی کاربر برگرفته ازcontext. - مهندسی بافتار و خلاصهسازی:
SummarizationMiddlewareبه همراه یک تریگر. - انسان در چرخه، دستهای و بهازای هر فراخوانی: بررسی از نوع
per_callرویsend_email.
کد برنامه
ایجنت هر دو شیء پایداری دادهها و دو میانافزار را دریافت میکند. تریگر خلاصهسازی روی 10 پیام تنظیم شده و خلاصه، 4 پیام آخر را نگه میدارد:
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 مینویسد تا در طول اجرا بتوان تعداد دفعات اجرای ابزار را شمرد:
@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-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-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-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 را فراخوانی کرد و هر دو واقعیت را در مخزن یافت. شکل هر فرایند را نشان میدهد.
اجرا با این سطرها در سه فایل به پایان رسید:
== 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.