بخش 8.1 · بهره‌برداری و نگهداری

سرور ایجنت: دستورهای langgraph dev ،up و deploy

Agent Server: langgraph dev, up, and deploy

فهرست مطالب
  1. سه دستور اصلی
  2. سقف بازگشت در سرور
  3. تعداد وظایف هر ورکر
  4. افزوده‌شدن حدود یک ثانیه به زمان هر اجرا
  5. ارسال پیام مجدد پیش از دریافت پاسخ قبلی (Double Texting)
  6. آنچه langgraph dev به LangSmith می‌فرستد
  7. نیاز langgraph up به کلید
  8. دستور langgraph deploy

سرور تحت langgraph dev در هر لحظه فقط یک وظیفه (Job) را اجرا می‌کند و بین 0.6 تا 1 ثانیه به زمان هر اجرا می‌افزاید؛ langgraph up نیز بدون کلید اصلاً شروع به کار نخواهد کرد.

ایجنت خود را از یک اسکریپت ساده به langgraph dev منتقل می‌کنید و هم‌زمان 16 درخواست به سمت آن می‌فرستید. میانه‌ی زمان اجرا به 71 ثانیه می‌رسد که 66 ثانیه‌ی آن صرف انتظار کشیدن قبل از شروع به کار مدل شده است. مستندات رسمی می‌گویند هر ورکر (Worker) به‌طور هم‌زمان 10 وظیفه را اجرا می‌کند و متن راهنمای --help نیز همین را می‌گوید؛ اما سرور در عمل فقط یکی را اجرا کرد. وقتی مدل روی CPU پردازش می‌شود، اجرای ده وظیفه به‌طور هم‌زمان سریع‌تر نیست.

پس از پایان این بخش، می‌توانید langgraph dev را اجرا کنید، تعداد وظایف هر ورکر را تنظیم نمایید، و سقف بازگشت (Recursion limit) و زمان اجرای هر فرایند را پیش‌بینی کنید. همچنین می‌توانید بر اساس اثرات ثبت‌شده، استراتژی مناسب برای ارسال پیام مجدد پیش از دریافت پاسخ قبلی (Double texting) را انتخاب کنید و نیازمندی‌های langgraph up و langgraph deploy را برشمرید.

سه دستور اصلی

سرور ایجنت (Agent Server): سرور LangSmith که گراف کامپایل‌شده را پشت یک API از جنس HTTP متشکل از دستیارها (Assistants)، رشته‌ها (Threads) و اجراها (Runs) اجرا می‌کند. این پکیج langgraph-api نام دارد و ما کدهای آن را مستقیماً در پکیج نصب‌شده بررسی کرده‌ایم.

رابط خط فرمان LangGraph یا همان langgraph-cli (نسخه‌ی فیکس‌شده‌ی 0.4.43)، سرور را به سه روش اجرا می‌کند {{docs langsmith/cli}}:

دستور چه چیزی را اجرا می‌کند نیازمندی‌ها
langgraph dev یک فرایند پایتون با محیط اجرای درون‌حافظه‌ای، روی 127.0.0.1:2024 pip install -U "langgraph-cli[inmem]" و پایتون 3.11 یا بالاتر
langgraph up ایمیج سرور داخل Docker، همراه با کانتینرهای Postgres و Redis داکر، و یک کلید API سرویس LangSmith برای مصارف محلی یا کلید لایسنس برای محیط عملیاتی
langgraph deploy بیلد گرفتن و push کردن به LangSmith که در ادامه وظیفه‌ی اجرای سرور را بر عهده می‌گیرد کلید API سرویس LangSmith، و داکر برای بیلد محلی

تمام این دستورها فایل langgraph.json را می‌خوانند؛ فایلی که شناسه‌ی گراف را به مسیر فایل و متغیر مربوط به گراف کامپایل‌شده متصل می‌کند {{docs langsmith/cli}}. برنامه‌ی آزمایشی ما سه گراف دارد:

فایل langgraph.json برنامهٔ آزمایشگاه capture/lab/T15-agent-server-x86/t15app/langgraph.json
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./graphs.py:agent",
    "slow": "./graphs.py:slow",
    "loop": "./graphs.py:loop"
  },
  "python_version": "3.13",
  "env": {}
}

گراف slow دو گره دارد که هر کدام به اندازه‌ی نصف مقدار seconds در ورودی می‌خوابند. گراف loop فقط یک گره دارد که یال خروجی‌اش دوباره به خودش برمی‌گردد. هیچ‌کدام مدل را فراخوانی نمی‌کنند. ایجنت این برنامه یک مدل ساختگی (Stand-in) داشت و هیچ‌یک از آمارهای این بخش از آن گرفته نشده است.

برای بررسی عملکردهای مبتنی بر مدل از برنامه‌ی دوم، یعنی t15rapp/، با دو گراف استفاده شد. گراف agent آن ایجنتی با متد create_agent متصل به Qwen3 4B روی Ollama و ابزار add است (t15rapp/graphs.py). گراف loopagent نیز ایجنتی است که ابزار آن همیشه می‌گوید دوباره آن را فراخوانی کن. سرویس Ollama روی CPU اجرا می‌شد و در هر لحظه تنها به یک فراخوانی مدل پاسخ می‌داد.

روی سرور ایجنت، چک‌پوینتر (Checkpointer) را به‌صورت ورودی پاس نمی‌دهید. بر اساس صفحه‌ی ایجنت‌ها، LangSmith هنگام استقرار، خودش یک چک‌پوینتر فراهم می‌کند و برای کارِ محلی باید نمونه را خودتان ارسال کنید {{docs oss/python/langchain/agents}}. بنابراین، ماندگاری داده‌ها که در یک اسکریپت ساده نیازمند SqliteSaver بود، همراه با سرور ارائه می‌شود.

سقف بازگشت در سرور

در صفحه‌ی متغیرهای محیطیِ سرور ایجنت، عدد 10011 به عنوان مقدار پیش‌فرض LANGGRAPH_DEFAULT_RECURSION_LIMIT تعیین شده است {{docs langsmith/env-var-cloud}}. ماژول پیکربندی پکیج langgraph-api نسخه‌ی 0.18.0 نیز دقیقاً همین عدد را قرار داده است {{code langgraph_api/utils/config.py}}. با این حال، مقدار پیش‌فرض خود کتابخانه برای یک StateGraph برابر با 10007 است؛ موضوعی که در بخش 6.8 نشان داده شد.

ما این متغیر را روی گراف loop تحت دستور langgraph dev روی ماشین مهمان x86 سرور با 32 هسته‌ی مجازی (vCPU) و 48 گیگابایت رم اندازه‌گیری کردیم. این گراف یک بار بدون تنظیمات اولیه و بار دیگر با سقف 50 اجرا شد:

یک گراف حلقه‌ای در langgraph dev، بدون پیکربندی capture/lab/T15-agent-server-x86/02-recursion.jsonl
{"exp": "T15", "part": "recursion_limit", "server": "dev-default", "config": null, …'Recursion limit of 10007 reached without hitting a stop condition. …"n_in_state": 10007, "run_status": "error"}

سطر اول، برش‌خورده به متن خطا و تعداد گام‌ها.

اجرا پس از 7.3 ثانیه و در گام 10007، با وضعیت error متوقف شد. با قرار دادن {"recursion_limit": 50} در تنظیمات، دقیقاً روی گام 50 ایستاد. بنابراین مقداری که صریحاً پاس می‌دهید اولویت دارد و پیش‌فرضی که در langgraph dev دریافت می‌کنید، همان مقدار پیش‌فرض کتابخانه است. این‌که چرا مقدار سرور اعمال نشد را ردگیری محاسبات نکردیم. این کتابچه تفاوت این سه عدد را با عنوان تعارض D105 ثبت کرده است. مقدار recursion_limit را در تمام اجراها دستی ارسال کنید تا به هیچ‌یک از مقادیر پیش‌فرض نیازی نداشته باشید.

ما همچنین گراف loopagent را به همراه مدل Qwen3 4B در langgraph dev با سقف {"recursion_limit": 25} طی سه بار اجرا سنجیدیم. هر اجرا پس از 13 بار فراخوانی مدل و 12 بار فراخوانی ابزار ظرف 24 ثانیه، با وضعیت error و خطای GraphRecursionError پایان یافت. در اجرای بدون تنظیمات اولیه، فرایند پس از 120 ثانیه و 58 بار فراخوانی مدل همچنان در حال اجرا بود که آن را لغو کردیم.

تعداد وظایف هر ورکر

تعداد وظایف هر ورکر (Jobs per worker): تعداد اجراهایی است که یک پردازنده‌ی صف در سرور ایجنت به‌طور هم‌زمان اجرا می‌کند. این مقدار از طریق متغیر محیطی N_JOBS_PER_WORKER یا آرگومان --n-jobs-per-worker در دستور langgraph dev مشخص می‌شود.

منابع دو مقدار پیش‌فرض متفاوت برای langgraph dev ذکر می‌کنند. متن راهنمای --help این گزینه می‌گوید مقدار پیش‌فرض برابر با 10 است {{code libs/cli/langgraph_cli/cli.py}}. خود این گزینه هیچ مقدار پیش‌فرضی ندارد و در نتیجه langgraph-api نسخه‌ی 0.18.0 عدد 1 را به کار می‌برد {{code langgraph_api/cli.py}}. زبانه‌ی پایتون در صفحه‌ی خط فرمان عدد 1 را نشان می‌دهد، اما زبانه‌ی جاوااسکریپت و راهنمای مقیاس‌پذیری عدد 10 را مبنا گذاشته‌اند {{docs langsmith/cli}} {{docs langsmith/agent-server-scale}}. این کتابچه اختلاف موجود را به عنوان تعارض D123 ثبت کرده و رفتار خود کد را ملاک قرار می‌دهد.

ما عملکرد سرور را با ارسال 20 اجرای پس‌زمینه برای گراف slow (هر کدام به مدت 2 ثانیه) روی ماشین مهمان سرور x86، به ازای هر تنظیم یک بار، اندازه گرفتیم. بدون هیچ تنظیمی، وظایف تک‌به‌تک اجرا شدند و کل 20 اجرا 41.0 ثانیه طول کشید. با تغییر گزینه به --n-jobs-per-worker 10، وظایف در دسته‌های ده‌تایی هم‌زمان پردازش شدند و کل فرایند 5.1 ثانیه زمان برد. با رساندن این مقدار به عدد 100، هر 20 وظیفه به‌طور هم‌زمان و در 3.5 ثانیه به پایان رسیدند.

با ایجنت مبتنی بر Qwen3 4B، اتمام 10 اجرای پس‌زمینه در حالت تک‌وظیفه‌ای 47.1 ثانیه و در حالت 10 وظیفه 44.4 ثانیه زمان برد. با تنظیم روی 10، تمامی 10 وظیفه در یک لحظه آغاز شدند، اما در ادامه، Ollama یکی پس از دیگری به فراخوانی‌های مدل پاسخ داد.

اجرا بر ثانیه در langgraph dev با Qwen3 4B، به تفکیک کلاینت‌های هم‌روندبا Qwen3 4B روی CPU، نرخ پردازش از 4 کلاینت به بعد روی 0.22 اجرا بر ثانیه باقی ماند، با 1 یا 10 وظیفه در هر ورکر.
اجرا بر ثانیه در langgraph dev با Qwen3 4B، بر حسب کلاینت‌های هم‌روند نمودار نقطه‌ای از اجرا بر ثانیه در برابر کلاینت‌های هم‌روند 1، 4 و 16 در مقیاس لگاریتمی برای langgraph dev روی مهمان سرور x86 با ایجنت Qwen3 4B روی CPU، هر نقطه یک اجرای بار. پیش‌فرضِ یک وظیفه به ازای هر ورکر: 0.185، 0.222، 0.223 اجرا بر ثانیه. ده وظیفه به ازای هر ورکر: 0.191، 0.224، 0.226. تمام 104 اجرا بدون خطا و به‌درستی پاسخ دادند. 0 0.05 0.1 0.15 0.2 0.25 0.3 1 4 16 کلاینت‌های هم‌روند اجرا بر ثانیه 10 وظیفه به ازای هر ورکر پیش‌فرض، 1 وظیفه هر نقطه یک اجرای بار از گراف ایجنت است: 10 اجرا در 1 و 4 کلاینت، 32 در 16. ‏Ollama در هر لحظه به یک فراخوانی پاسخ داد؛ 0.44 تا 0.45 بر ثانیه از 4 کلاینت به بعد.
هر نقطه یک اجرای بار روی مهمان سرور x86 است؛ 10 اجرا در 1 و 4 کلاینت و 32 اجرا در 16 کلاینت. هر اجرا متعلق به ایجنت Qwen3 4B از طریق runs.wait روی یک ریسهٔ جدید است. برگرفته از capture/lab/summary/agent-server-x86-real.json.

ما همچنین یک بار کاری را روی گراف agent متصل به Qwen3 4B روی همان ماشین مهمان سنجیدیم. هر درخواست یک رشته ایجاد می‌کرد و منتظر یک اجرا می‌ماند. هر سطح بار تنها یک بار اجرا شد. نمودار نرخ پردازش (Throughput) را نشان می‌دهد. تمام 104 اجرا (شامل 10، 10 و 32 اجرا به ازای هر سطح) بدون هیچ خطایی پاسخ درست را بازگرداندند.

تعداد وظایف هر ورکر 1 کلاینت 4 کلاینت 16 کلاینت
پیش‌فرض (1) 0.185 اجرا در ثانیه، p50 برابر با 5,420 میلی‌ثانیه 0.222 اجرا در ثانیه، p50 برابر با 17,635 میلی‌ثانیه 0.223 اجرا در ثانیه، p50 برابر با 70,680 میلی‌ثانیه
10 0.191 اجرا در ثانیه، p50 برابر با 5,129 میلی‌ثانیه 0.224 اجرا در ثانیه، p50 برابر با 17,188 میلی‌ثانیه 0.226 اجرا در ثانیه، p50 برابر با 56,033 میلی‌ثانیه

وقتی ظرفیت ورکر روی 1 تنظیم باشد، صف درون سرور شکل می‌گیرد. در حالت 16 کلاینت، یک اجرا حدود 66 ثانیه قبل از اولین فراخوانی مدل در صف ماند. با افزایش مقدار به 10، صف به داخل Ollama منتقل شد و زمان پردازش مدل برای هر اجرا از 4.4 ثانیه به 43.8 ثانیه رسید. نرخ پردازش را در اصل مدل تعیین می‌کند که در حالت 16 کلاینت حدود 0.45 فراخوانی مدل در ثانیه است و تغییر این گزینه تغییری در آن ایجاد نمی‌کند. با این حال، اگر مدل می‌تواند فراخوانی‌ها را به‌صورت موازی پاسخ دهد، آن را روی 10 بگذارید.

افزوده‌شدن حدود یک ثانیه به زمان هر اجرا

در حالت تک‌کلاینت، هر اجرا بین 5.1 تا 5.5 ثانیه طول می‌کشید که 4.4 ثانیه‌ی آن به دو فراخوانی مدل اختصاص داشت. ما دو شیوه‌ی راه‌اندازی برای اجرای ایجنت متصل به Qwen3 4B را روی ماشین مهمان سرور x86 آزمایش کردیم. هر شیوه 10 بار، به صورت جداگانه، با هر سطح از ظرفیت وظایف اجرا شد. ستون آخر جدول، تفاوت زمان دیده‌شده از سمت کلاینت با مدت‌زمانِ سپری‌شده داخل فراخوانی‌های مدل است:

نحوه‌ی آغاز اجرا زمان کلاینت، p50 زمان مدل، p50 تأخیر اضافه‌شده از سمت سرور، p50
runs.wait با ظرفیت پیش‌فرض 5,486 میلی‌ثانیه 4,473 میلی‌ثانیه 1,014 میلی‌ثانیه
runs.create و سپس runs.join با ظرفیت پیش‌فرض 5,443 میلی‌ثانیه 4,429 میلی‌ثانیه 1,015 میلی‌ثانیه
runs.wait با ظرفیت 10 5,139 میلی‌ثانیه 4,443 میلی‌ثانیه 661 میلی‌ثانیه
runs.create و سپس runs.join با ظرفیت 10 5,087 میلی‌ثانیه 4,385 میلی‌ثانیه 651 میلی‌ثانیه

تقریباً تمام این زمان اضافه پیش از نخستین فراخوانی مدل شکل گرفت. این انتظار در حالت پیش‌فرض حدود 1,003 میلی‌ثانیه و با ظرفیت ده‌تایی بین 641 تا 651 میلی‌ثانیه بود. بخشی از این موضوع به صف محیط اجرای درون‌حافظه‌ای مربوط می‌شود؛ سازوکاری که در صورت نیافتن اجرا در هر بار بررسی (Poll)، به مدت 0.5 ثانیه به خواب می‌رود {{code langgraph_runtime_inmem/ops.py}}. باقی دلایل این تأخیر را ردگیری محاسبات نکردیم. این کفِ تأخیر را به عنوان یکی از ویژگی‌های ذاتی نسخه‌ی فعلی langgraph dev در نظر بگیرید. بررسی کف تأخیر برای langgraph up همراه با Postgres و Redis در ویرایش بعدی منتشر خواهد شد.

ارسال پیام مجدد پیش از دریافت پاسخ قبلی (Double Texting)

ارسال پیام مجدد (Double texting): ارسال یک اجرای دوم روی رشته در حالی که اجرای اول روی همان رشته هنوز در حال پردازش است. سرور ایجنت یکی از چهار استراتژی چندوظیفگی را انتخاب می‌کند که پیش‌فرض آن enqueue است {{docs langsmith/double-texting}}.

مستندات می‌گویند که مدیریت پیام مجدد یکی از قابلیت‌های اختصاصی سرور است و LangGraph متن‌باز این امکان را ندارد {{docs langsmith/double-texting}}. نحوه‌ی کار با رشته‌ها داخل اسکریپت‌ها در بخش 5.2 آمده است.

اسکریپت آزمایش ما اجرای A از گراف slow را به مدت 4 ثانیه کلید می‌زند. پس از 1 ثانیه، اجرای B را با زمان 2 ثانیه روی همان رشته و همراه با یک استراتژی ارسال می‌کند:

اجرای دوم در هر سناریوی ارسال پیام متوالی (double texting) capture/lab/T15-agent-server-x86/t15_drive.py
        r1 = await client.runs.create(tid, "slow", input={"seconds": 4, "label": f"{strategy}-A"})
        await asyncio.sleep(1.0)
…
            r2 = await client.runs.create(tid, "slow", input={"seconds": 2, "label": f"{strategy}-B"}, multitask_strategy=strategy)

برش‌خورده به دو اجرا و زمان انتظار بین آن‌ها.

ما رفتار تک‌تک استراتژی‌ها را یک بار در محیط langgraph dev روی ماشین مهمان سرور x86 آزمودیم. تصویر وضعیت گره‌های هر دو اجرا را روی یک محور زمانی نمایش می‌دهد.

گره‌های اجرای A و اجرای B تحت هر استراتژی چندوظیفگیحالت reject اجرای B را رد کرد، enqueue آن را پس از A اجرا کرد، interrupt اجرای A را متوقف ساخت و گره ناتمامش را از بین برد، و rollback اجرای A را حذف کرد.
گره‌های اجرای A و اجرای B تحت هر استراتژی چندوظیفگی چهار خط زمانی از 0 تا 7 ثانیه، هر کدام یک ریسه در langgraph dev روی مهمان سرور x86. اجرای A دو گرهٔ 2 ثانیه‌ای دارد و اجرای B که حدود 1 ثانیه بعد روی همان ریسه ارسال شده، دو گرهٔ 1 ثانیه‌ای را اجرا می‌کند. در reject، اجرای B با HTTP 409 رد می‌شود و A به پایان می‌رسد. در enqueue، اجرای B با اتمام A در ثانیهٔ 4.8 آغاز می‌شود. در interrupt، اجرای B در ثانیهٔ 1.0 آغاز می‌شود و گرهٔ اول A هرگز تمام نمی‌شود. در rollback، گرهٔ اول A درست قبل از ارسال B شروع می‌شود، B در ثانیهٔ 1.0 آغاز می‌گردد و A حذف می‌شود. اجرای B ارسال شد REJECT ‏B رد شد، خطای HTTP 409 A B اول دوم ‏409، چیزی اجرا نشد ENQUEUE ‏B منتظر A می‌ماند سپس اجرا می‌شود A B اول دوم اول دوم INTERRUPT ‏A متوقف و گره آن از دست رفت A B گره اول A هرگز ثبت نشد اول دوم ROLLBACK ‏A حذف شد، B تنها اجرا می‌شود A B گره اول A هرگز ثبت نشد اول دوم 0 s 1 s 2 s 3 s 4 s 5 s 6 s 7 s مسیر A: گره‌های اجرای A، توپر. مسیر B: گره‌های اجرای B، توخالی. خط‌چین سرخابی: گره‌ای از ‏A که شروع شد ولی هرگز ثبت نشد. زمان‌ها از رویدادهای گره گرفته شده، هر کدام یک اجرا.
هر مسیر یک ریسه روی مهمان سرور x86 است. نوار پررنگ گره‌ای از اجرای A است و نوار توخالی گره‌ای از اجرای B. خط سرخابی‌رنگ زمان ارسال اجرای B را نشان می‌دهد. برگرفته از capture/lab/summary/agent-server-x86.json.
استراتژی وضعیت اجرای B وضعیت اجرای A وضعیت داده‌ها و تاریخچه در پایان
reject امتناع مدل با HTTP 409 با موفقیت (success) خاتمه یافت فقط رخدادهای ثبت‌شده‌ی A؛ 4 رکورد در تاریخچه
enqueue منتظر ماند، سپس با پایان A آغاز شد با موفقیت (success) خاتمه یافت ابتدا رخدادهای A، سپس رخدادهای B؛ 8 رکورد در تاریخچه
interrupt بلافاصله آغاز شد وضعیت آن به interrupted تغییر یافت فقط رخدادهای ثبت‌شده‌ی B؛ 6 رکورد در تاریخچه
rollback بلافاصله آغاز شد حذف شد؛ درخواست خواندن آن خطای NotFoundError داد فقط رخدادهای ثبت‌شده‌ی B؛ 4 رکورد در تاریخچه

پیام امتناع در استراتژی reject نام دیگر استراتژی‌ها را هم می‌آورد:

رد شدن در حالت reject capture/lab/T15-agent-server-x86/04-double-texting.jsonl
{"exp": "T15", "part": "double_texting", "server": "dev-default", "strategy": "reject", "second_run": {"accepted": false, "type": "ConflictError", "http_status": 409, "body": "{\"detail\":\"Thread is already running a task. Wait for it to finish or choose a different multitask strategy.\"}"}, …

سطر اول، برش‌خورده به اجرای دوم.

مستندات می‌گویند که interrupt پیشرفت اجرای نخست را تا نقطه‌ی اعمال وقفه حفظ می‌کند {{docs langsmith/double-texting}}. در آزمایش ما، چون اجرای A داخل اولین گره خود بود، هنوز گام پایان‌یافته‌ای برای نگه‌داشتن نداشت. بنابراین گره آن هرگز مقداری ننوشت و رشته فقط اجرای B را در خود نگه داشت. فراخوانی ابزاری که در آن گره شروع شده بود نیز بی‌پاسخ می‌ماند؛ نکته‌ای که مستندات هم درباره‌اش هشدار داده‌اند. برای رشته‌های چت گزینه‌ی enqueue را انتخاب کنید، و اگر نیاز است ارسال پیام دوم مشروط به تلاش مجدد خود کاربر باشد، reject را برگزینید.

آنچه langgraph dev به LangSmith می‌فرستد

اگر متغیرهای محیطی برنامه ردیابی را فعال کرده باشند، langgraph dev هر اجرا را ثبت می‌کند. ما این فرایند را روی مک با یک کلید از حساب رایگان LangSmith در یک محیط موقت (Scratch) سنجیدیم. نسخه‌های مورد استفاده langgraph-cli 0.4.43، langgraph-api 0.18.0 و langgraph-runtime-inmem 0.38.0 بودند. هر پنج اجرای آزمایشی ایجنت مبتنی بر Qwen3 4B از مسیر سرور به‌درستی پاسخ دادند.

  • اجراها (Runs): روی حساب کاربری 35 اجرا ذخیره شد؛ یعنی 7 اجرا به ازای هر اجرای سرور. گره ریشه در هر ردگیری محاسبات با نام agent (همان شناسه‌ی گراف) ثبت شده بود، نه با عنوان LangGraph. شناسه‌ی آن همان شناسه‌ی اجرای سرور است.
  • متادیتای ریشه (Metadata): شامل مقادیر thread_id، assistant_id، graph_id و run_attempt بود. متغیرهای langgraph_api_version با مقدار 0.18.0، langgraph_host با مقدار self-hosted، و langgraph_plan با مقدار enterprise نیز در آن وجود داشتند. مقدار LANGSMITH_LANGGRAPH_API_VARIANT نیز برابر با local_dev بود.
  • درخواست‌های شبکه: فرایند تنها با یک میزبان یعنی api.smith.langchain.com ارتباط برقرار کرد. طی این مدت 2 درخواست GET /info و 15 درخواست POST /runs/multipart فرستاده شد و هیچ درخواستی برای بررسی لایسنس ارسال نشد.
درخواست‌های langgraph dev برای پنج اجرای ردگیری‌شده capture/lab/summary/langsmith-account-mac.json
  "hosts": [
   "https://api.smith.langchain.com"
  ],
  "requests": {
   "GET /info 200": 2,
   "POST /runs/multipart 202": 15
  },

پکیج langgraph-api هنگام ایمپورت، ماژول truststore را داخل لایه‌ی SSL قرار می‌دهد؛ به همین دلیل سرور گواهی‌ها را با مخزن مورد اعتماد سیستم‌عامل ارزیابی می‌کند {{code langgraph_api/server.py:11-17}}. در یک ساندباکس (Sandbox) که دسترسی به این مخزن بسته باشد، هیچ ردگیری به API نمی‌رسد. متغیر محیطی DISABLE_TRUSTSTORE=true این تزریق را خاموش می‌کند و اجرای ثبت‌شده‌ی ما نیز از همین تنظیم استفاده کرد. بخش 8.2 یک رابط کاربری چت را با خاموش بودن ردیابی در مقابل همین سرور قرار می‌دهد.

نیاز langgraph up به کلید

دستور langgraph up ایمیج اپلیکیشن شما را بر پایه‌ی langchain/langgraph-api می‌سازد و آن را همراه با Postgres و Redis اجرا می‌کند. این دستور پیش از آغاز بیلد، نیازمندی‌هایش را چاپ می‌کند:

سطرهای نخست langgraph up capture/lab/T15-agent-server-x86/08-up-start-excerpt.txt
Starting Agent Server...
For local dev, requires env var LANGSMITH_API_KEY with access to LangSmith Agent Server.
For production use, requires a license key in env var LANGGRAPH_CLOUD_LICENSE_KEY.

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

کانتینرها پس از اجرای langgraph up capture/lab/T15-agent-server-x86/09-up-containers.txt
t15app-langgraph-api-1 t15app-langgraph-api Exited (3) Less than a second ago
t15app-langgraph-redis-1 redis:6 Up 11 seconds (healthy)
t15app-langgraph-postgres-1 pgvector/pgvector:pg16 Up 11 seconds (healthy)
لاگ کانتینر API capture/lab/T15-agent-server-x86/10-up-license-excerpt.txt
ValueError: License verification failed. Please ensure proper configuration:
- For local development, set a valid LANGSMITH_API_KEY for an account with LangGraph Cloud access in the environment defined in your langgraph.json file.
- For production, configure the LANGGRAPH_CLOUD_LICENSE_KEY environment variable with your LangGraph Cloud license key.
Review your configuration settings and try again. If issues persist, contact support for assistance.

بنابراین، سروری که با کانتینرهای Postgres و Redis پیکربندی شده باشد، حتی روی ماشین خودتان هم بدون حساب کاربری یا لایسنس بالا نخواهد آمد.

سپس یک کلید از حساب رایگان LangSmith تهیه کردیم. از آنجا که داکر روی مک در حال اجرا نبود، langgraph up با پیغام Error: Docker not installed or not running و کد خروجی 2 متوقف شد. برنامه حتی پیش از ارزیابی کلید کار را متوقف کرد.

پکیج langgraph_license از مخزن PyPI (که با langgraph-api 0.18.0 نصب می‌شود) در تمام ارزیابی‌ها مقدار true برمی‌گرداند {{code langgraph_license/validation.py}}. اعتبارسنجیِ ناموفقِ بالا صرفاً درون ایمیج خود سرور اجرا می‌شود. بنابراین هنوز مطمئن نیستیم که آیا کلیدِ یک حساب رایگان از سد این بررسی می‌گذرد یا نه. حساب سازمانی مقدار can_use_langgraph_cloud را برابر false و سهمیه‌ی استقرار رایگان را 0 گزارش کرد. این مورد صرفاً نشانه‌ای از سمت API است، نه یک آزمون ارزیابی (Probe) عملی.

آزمون‌های مربوط به پشته‌ی کامل سرور در ویرایش بعدی می‌آیند و در بخش 8.8 فهرست شده‌اند: از کار افتادن ورکر، قطعی موقت Redis یا Postgres، تضمین اجرای دقیقاً یک‌بار (Exactly once) در صف وظایف، و آنچه درون Redis نگه‌داری می‌شود.

دستور langgraph deploy

این بخش صرفاً بر اساس مستندات و بررسی کدها نوشته شده است؛ چرا که ما langgraph deploy را شخصاً اجرا نکردیم، زیرا پلن رایگان حساب کاربری ما هیچ ظرفیت استقرار رایگانی گزارش نمی‌داد.

دستور langgraph deploy ایمیج را می‌سازد، آن را به رجیستری مدیریت‌شده‌ی LangSmith ارسال (push) می‌کند، و در یک مرحله یک سرور ایجنت را ایجاد یا به‌روزرسانی می‌کند {{docs langsmith/cli}}. بدون داکر، این دستور از LangSmith می‌خواهد تا ایمیج را از روی فایل‌های سورس آپلودشده بسازد. این دستور در مستندات وضعیت بتا دارد.

  • کلید دسترسی: این دستور متغیرهای --api-key، یا LANGGRAPH_HOST_API_KEY، LANGSMITH_API_KEY یا LANGCHAIN_API_KEY را می‌خواند {{code libs/cli/langgraph_cli/deploy.py}}.
  • نوع سرور: سرور جدید در حالت پیش‌فرض serverless است، مگر آنکه پارامتر --agent-server-type dedicated را اضافه کرده باشید {{code libs/cli/langgraph_cli/deploy.py:116}}. این مقدار پیش‌فرض در درخت مخزن مربوط به نسخه‌ی 1.2.22 وجود دارد که تازه‌تر از نسخه‌ی نصبی 0.4.43 است. نسخه‌ی 0.4.43 پیش‌فرض خود را داخل گزینه‌ی click تنظیم می‌کند. مخزن اصلی همچنین برای بسترهای داده‌ای بدون قابلیت کاهش به صفر (Scale to zero)، گزینه‌ی dev را برمی‌گزیند {{code libs/cli/langgraph_cli/deploy.py:1568-1570}}. نسخه‌ی نصبی فعلی چنین قاعده‌ای ندارد و صرفاً در صورت مواجهه با خطای 400 از سوی AWS استفاده از --agent-server-type dev را پیشنهاد می‌کند. این گزینه نام‌های قدیمی‌تر dev و prod را هم می‌پذیرد. مستندات می‌گویند که معماری سرورلس ظرفیت را تا صفر پایین می‌آورد و شروع سرد (Cold start) دارد {{docs langsmith/cloud-platform-features}}.
  • رجیستری اختصاصی: نسخه‌های خودمیزبان (Self-hosted) LangSmith به فلگ --push-to برای معرفی رجیستری دلخواه یا --image-uri همراه با کد هش ایمیج نیاز دارند {{docs langsmith/cli}}.
  • سایر دستورها: دستورهای langgraph deploy list، deploy metrics و deploy listeners پروژه‌های مستقرشده‌ی شما را بررسی و گزارش می‌کنند {{code libs/cli/langgraph_cli/deploy.py}}.

گزارش امنیتی GHSA-8prr-f582-jqq3 اعلام می‌کند که دستور langgraph deploy --verbose توکن push رجیستری را در نسخه‌های 0.4.15 تا 0.4.31 از langgraph-cli آشکار می‌کرد. نسخه‌ی فیکس‌شده‌ی ما یعنی 0.4.43 خارج از این بازه است. با این حال، همیشه پارامتر --verbose را از لاگ‌های محیط‌های یکپارچه‌سازی مداوم (CI) دور نگه دارید؛ زیرا خروجی بیلد و push داکر را کاملاً نمایش می‌دهد.

بدون داشتن لایسنس، می‌توانید همان ایجنت را از طریق برنامه‌ی شخصی خود روی FastAPI بالا بیاورید. در بخش 9.1 این سرویس را طراحی می‌کنیم و در بخش 9.7 آن را با چند ورکر و یک قفل Postgres به ازای هر رشته اجرا خواهیم کرد.

منابع: capture/lab/summary/langsmith-account-mac.json، capture/lab/T21-langsmith-account-mac/07-e5-dev-inspect.json، capture/lab/T21-langsmith-account-mac/07-e5-dev-netlog.jsonl، capture/lab/T21-langsmith-account-mac/07-e5-dev-runs.jsonl، capture/lab/T21-langsmith-account-mac/07-e5-up.txt، capture/lab/T21-langsmith-account-mac/07-e5-server-venv-freeze.txt، capture/lab/T21-langsmith-account-mac/01-account-probe.json، capture/lab/T21-langsmith-account-mac/_scripts/t21_e5_client.py، capture/lab/T21-langsmith-account-mac/_scripts/t21_e5_inspect.py؛ کدهای langgraph_api/server.py و langgraph_license/validation.py در langgraph-api 0.18.0؛ capture/lab/summary/agent-server-x86-real.json، capture/lab/T15-agent-server-x86-real/01-recursion.jsonl، capture/lab/T15-agent-server-x86-real/02-load.jsonl، capture/lab/T15-agent-server-x86-real/03-floor.jsonl، capture/lab/T15-agent-server-x86-real/04-workers.jsonl، capture/lab/T15-agent-server-x86-real/t15r_drive.py، capture/lab/T15-agent-server-x86-real/t15rapp/graphs.py، capture/lab/summary/agent-server-x86.json، capture/lab/T15-agent-server-x86/02-recursion.jsonl، capture/lab/T15-agent-server-x86/03-workers.jsonl، capture/lab/T15-agent-server-x86/04-double-texting.jsonl، capture/lab/T15-agent-server-x86/08-up-start-excerpt.txt، capture/lab/T15-agent-server-x86/09-up-containers.txt، capture/lab/T15-agent-server-x86/10-up-license-excerpt.txt، capture/lab/T15-agent-server-x86/t15_drive.py، capture/lab/T15-agent-server-x86/t15app/graphs.py، capture/lab/T15-agent-server-x86/t15app/langgraph.json؛ کدهای libs/cli/langgraph_cli/cli.py و libs/cli/langgraph_cli/deploy.py در langgraph-cli 0.4.43؛ langgraph_api/utils/config.py و langgraph_api/cli.py در langgraph-api 0.18.0؛ langgraph_runtime_inmem/ops.py در langgraph-runtime-inmem 0.38.0؛ docs.langchain.com در commit مستندات به شناسه‌ی 04d4d4a (شامل langsmith/cli، langsmith/env-var-cloud، langsmith/agent-server-scale، langsmith/double-texting، langsmith/cloud-platform-features، oss/python/langchain/agents)؛ توصیه‌نامه‌ی امنیتی GHSA-8prr-f582-jqq3.

ترجمه‌ی فارسی Agent Server: langgraph dev, up, and deploy از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما