این مستند سازوکار استک پایتونی LangChain را در یک نسخهی دقیقاً قفلشده (Pin) بررسی میکند، و تمام نمونهکدهای ارائهشده از خروجی واقعیِ اجراهایی استخراج شدهاند که خودتان هم میتوانید آنها را بیازمایید.
مخاطبان این مستند
اگر به زبان Python کد میزنید و سابقهی فراخوانی API مدلهای چت را دارید، این راهنما برای شماست. شاید کدهای قدیمیتر LangChain (نسخههای 0.x) را با زنجیرهها، ساختار AgentExecutor و ایمپورتهای بستهی langchain_community دیده باشید. اما امروز دستور pip install langchain روی Python 3.11 نسخهی 1.5.0 را نصب میکند و بیشتر آن کدهای قدیمی اصلاً ایمپورت نمیشوند.
این مستند برای مهندسانی نوشته شده است که ابتدا باید بسنجند آیا استک نسخهی 1.x به کارشان میآید یا نه، و سپس سیستم خود را بر پایهی آن بسازند. کار با همین تصمیمگیری آغاز میشود؛ تصمیمی که بر اساس ارزیابی روی مجموعهای از وظایف با مدلهای محلی و مدلهای Claude سنجیده شده است. هر بخش با گزارهای شروع میشود که اجراهای آزمایشی ما مؤید آن هستند و بیشتر بخشها با برنامهای کوچک برای بهکارگیری آن گزاره به پایان میرسند.
چهار پروژه نام LangChain را به اشتراک دارند: LangChain، LangGraph، LangSmith و Deep Agents. بستههای آنها نیز شماره نسخهی اختصاصی خود را دارند؛ بنابراین در این مستند، هر جا نام بستهای برده میشود شماره نسخهی آن نیز میآید؛ مانند langchain 1.5.0 و langchain-core 1.8.0. در بخش 1.1 وظیفهی هر پروژه بهروشنی آمده است.
پس از خواندن این مستند چه کارهایی میتوانید انجام دهید
- استک را از روی یک فایل قفل (Lockfile) روی Python 3.11 یا بالاتر نصب کنید و بگویید هر ایمپورت از کدام بسته میآید.
- با
create_agentیک ایجنت (Agent) بسازید و تمام فراخوانیهای مدل، فراخوانیهای ابزار (Tool call) و چکپوینتهای (Checkpoint) هر اجرا را پیشبینی کنید. - راهبرد خروجی ساختاریافته (Structured Output) و مجموعهای از میانافزارها (Middleware) را انتخاب کنید و ترتیب اجرای هوکهای آنها را پیشبینی نمایید.
- یک اجرا را در حالت مورد نیاز استریم کنید و با یک چکپوینتر (Checkpointer)، گفتوگو را در طول نوبتهای مختلف و حتی پس از راهاندازیهای مجدد حفظ کنید.
- اجرای فرایند را برای تأیید انسانی متوقف کنید، آن را ادامه دهید و بگویید هنگام ازسرگیری کدام کدها دوباره اجرا میشوند.
- تعداد تلاشهای هر لایهی تلاش مجدد را بشمارید و اثر جانبی را طوری طراحی کنید که بازپخش (Replay) پس از خرابی خطری ایجاد نکند.
- ابزارهای MCP، یک بازیاب (Retriever)، Deep Agents و ردگیری محاسبات (Tracing) در LangSmith را به هم متصل کنید و علت خرابی را از روی پیام خطای آن بیابید.
- ایجنت را از طریق FastAPI بههمراه Postgres، تأییدیهها، اسپنها (Span) و ارزیابیها سرو کنید و ابعاد آن را بر اساس سرور مدل تعیین کنید.
روش تدوین این مستند
ما نسخهی استک را روی انتشار 1.5.0 بستهی langchain در تاریخ 2026-11-11 قفل کردیم و در تاریخ 2026-11-14 تمامی گزارهها و جزئیات را دوباره سنجیدیم. سورسکد هر بسته را در تگِ مشخص آن و مستندات را در یک commit مشخص از مخزن (Repository) مطالعه کردیم و هر آنچه را هر دو میگفتند اجرا کردیم.
| بسته | نسخه | Commit |
|---|---|---|
langchain |
1.5.0 | c2f4036e |
langchain-core |
1.8.0 | a4b4a7b9، همان ساختار درختیِ libs/core در c2f4036e |
langgraph |
1.2.22 | 08a20169 |
langgraph-checkpoint, langgraph-prebuilt |
4.3.2, 1.1.2 | 08a20169 |
langgraph-checkpoint-sqlite |
3.1.3 | 5bd231cb |
deepagents |
0.7.38 | c858b364 |
langsmith |
0.14.17 | 15dd2a78 |
langchain-openai, langchain-anthropic, langchain-ollama |
1.8.0, 1.7.10, 1.1.0 | تگهای اختصاصی خودشان |
منابع رتبهبندی مشخصی دارند. هر جا میان دو منبع اختلافی باشد، منبع با رتبه بالاتر ملاک است و در همان بخش به این تفاوت اشاره شده است.
| رتبه (Rank) | منبع | آنچه مستند از آن میگیرد | نحوه ارجاع |
|---|---|---|---|
| 1 | سورسکد در تگهای فوق | تمام کلاسها، پارامترها، مقادیر پیشفرض و متن خطاها | code |
| 2 | مستندات رسمی در docs.langchain.com، ساختهشده از commit با شناسهی 04d4d4a از مخزن آن، با مجوز MIT |
رفتار مستندشده، با نگارش و بیان خودمان | docs |
| 3 | گزارش تغییرات (Changelog) و یادداشتهای انتشار هر بسته | زمان اعمال تغییر و اینکه در کدام بسته بوده است | docs برای صفحهی گزارش تغییرات، code برای یک انتشار |
| 4 | بستهی ثبت آزمایشها در capture/ |
تمام نمونهکدها و خروجیها | نام فایل |
| 5 | ثبتهای آزمایشگاهی در capture/lab/ |
تمام اعداد و ارقام حاصل از اندازهگیریها | نام فایل |
ایشیوها (Issue) و pull requestهای گیتهاب شواهدی (Evidence) عینی برای اثبات رفتار فریمورک در این نسخهی قفلشده هستند و در متن با شماره اختصاصیشان نام برده شدهاند. صفحات محصول در سایت www.langchain.com مجوز باز ندارند. بخش 1.1 ادعاهای آنها را با بیان خودمان نقل کرده و هر یک را در کنار نتایج آزمایشهای ما قرار میدهد.
سایت مستندات branch اصلی خود را نمایش میدهد و هیچ تگی از مستندات با نسخههای منتشرشده همخوانی ندارد. بنابراین یک صفحه ممکن است رفتاری جدیدتر یا قدیمیتر از نسخهی قفلشده را شرح دهد. هر جا میان صفحه و سورسکد اختلافی باشد، ملاک کد است و آن بخش هر دو حالت را نشان میدهد.
بستهی ثبت آزمایشها و آزمایشگاه
بستهی ثبت آزمایشها (Capture kit): برنامهای در مسیر capture/ که استک را درون یک فرایند (Process) پایتون پیش میبرد و آنچه را میبیند در capture/out/ مینویسد. این برنامه بخشهای LangChain، LangGraph، Deep Agents، langchain.mcp و SDK لانگاسمیت را پوشش میدهد.
این کیت از هیچ مدل چت ساختگی استفاده نمیکند. هر جا سناریویی به مدل نیاز داشته باشد، مدل Qwen3 4B Instruct با شناسهی qwen3:4b-instruct-2507-q4_K_M را از طریق ChatOllama فراخوانی میکند. تنظیمات عبارت بودند از: دمای 0، seed برابر با 42، num_ctx برابر با 16384 و num_predict معادل 512. ما این خروجیها را روی سیستم میهمان سرور x86، روی CPU و در تاریخ 2026-11-14 ضبط کردیم. نام مدل، تنظیمات، ماشین و تاریخ در هر فایل آمده است.
سایر مواردِ ثبتشده نیازی به مدل ندارند؛ مانند نسخهها، پیامها، ساختار گراف و مخزن داده (Store). اینها بدون نیاز به اتصال شبکه یا کلید اجرا میشوند و در هر بار اجرا دقیقاً بایتهایی یکسان تولید میکنند. این برنامه مقادیری را که در هر اجرا تغییر میکنند (مانند شناسههای پیام و زمانبندیهای هر پاسخ) ماسک میکند. یک مدل واقعی با کلمات خودش پاسخ میدهد؛ بنابراین فهرستهای خروجی عیناً عملکرد مدل را در اجرای ما نشان میدهند، حتی در جاهایی که پرامپت (Prompt) خواستهی بیشتری داشته است.
ثبتهای آزمایشگاهی (Lab recording): اجرا در برابر یک مدل واقعی یا پایگاه داده واقعی روی یکی از ماشینهای ما است که بهصورت فایلهای خام در capture/lab/ نگهداری میشوند. اسکریپت capture/run.py خلاصهی هر مجموعه داده را در capture/lab/summary/ محاسبه میکند و هر نمودار یکی از این خلاصهها را میخواند.
ما آزمایشها را روی دو ماشین ثبت کردیم. Mac یک Apple M1 Max با 10 هسته و 64 GiB رم، بههمراه Ollama و PostgreSQL 14 است. سیستم میهمان سرور x86 دارای 32 vCPU و 48 GiB رم، با PostgreSQL 16، Redis 7 و نسخه 0.31.1 از Ollama روی CPU است. این دو ماشین با هم تفاوت دارند، بنابراین این مستند هرگز عددی از یکی را در کنار عددی از دیگری قرار نمیدهد.
سیستم Mac یک لپتاپ اشتراکی بود و کارهای دیگری نیز در حین هر اجرای زمانبندیشده روی آن در جریان بود. هر زمان بهدستآمده از سیستم Mac را بهعنوان یک حد بالا (Upper bound) برای آن ماشین در نظر بگیرید. مدلهای محلی آزمایشگاه عبارت بودند از نسخههای 0.6B، 1.7B، 4B، 8B، 14B و 30B-A3B از Qwen3، مدل gpt-oss 20B روی Ollama و مدل nomic-embed-text برای امبدینگها (Embedding). بستهی ثبت آزمایشها از Qwen3 4B Instruct روی سرور x86 استفاده کرد؛ مانور شبیهسازی خرابی در بخش 8.7 و ماتریس کرشها در بخش 5.3 نیز همینطور. اجراهای آزمایشگاهی T05، T07، T08، T11، T17، T18 و T19 هم از همین مدل استفاده کردند.
بستر آزمایشی مجموعهوظایف (Task-suite bench): 99 وظیفهی (Task) معرفیشده در بخش 1.2 هستند که وضعیت نهایی ابزارهای بهکاررفته، صحت عملکرد هر یک را ارزیابی میکند. مدلهای Claude Haiku 5.5 (claude-haiku-5-5) و Claude Sonnet 5.5 (claude-sonnet-5-5) از طریق API شرکت Anthropic از روی Mac اجرا شدند. بودجه دارای سقف مشخصی بود و تمام فراخوانیها در یک دفتر هزینهها ثبت شدهاند. در روش اجرای بنچمارک، وظایف، تنظیمات و ردیفهایی که نباید استفاده شوند شرح داده شده است.
مدل Claude Haiku 5.5 همچنین 20 مورد ارزیابی سرویس محیط عملیاتی (Production) را در بخش 9.6 اجرا کرد که تمام هزینههای آن در دفتری از همان دست ثبت شد. این مدل همچنین 60 حمله علیه قوانین دسترسی به فایلها را در بخش 8.4 انجام داد که مجموعاً 0.021 دلار هزینه داشت. ماتریس قوانینِ آن بخش اصلاً مدلی ندارد؛ یک فراخوان اسکریپتی لایهی دسترسیها را هدایت میکند و در متن بخش نیز این موضوع آمده است. سایر زمانبندیهای ذکرشده برای مدلها در این مستند، زمان یک مدل محلی است.
قواعد نگارشی و علائم متن
- ارجاعهایی مانند
{{docs oss/python/langchain/models}}در سورسکدِ بخشها باقی میمانند و چیزی در نسخه خروجی چاپ نمیکنند. در نمای خواننده هیچ مسیر فایلی دیده نمیشود. - منابع همگی با کلمات خودمان بازگو شدهاند. گیومه «» فقط برای رشتههای عینی مانند خروجی و متن خطاها به کار میرود.
- ارجاع با کلید
docsنشاندهندهی مسیر صفحه در docs.langchain.com است که در commit مستندات به شناسهی04d4d4aخوانده شده است. - نمونهکدها از یکی از فایلهای ثبتشده بریده شدهاند. علامت
…در یک سطر جدا، سطرهای حذفشده را نشان میدهد و یادداشت زیر عنوان دلیل آن را شرح میدهد. - عبارات
<uuid-1>،<hex-1>و<time>در نمونهکدها مقادیر ماسکشده هستند. هر توکن (Token) یکسان درون یک فایل، نشاندهندهی مقداری یکسان است. - پاراگرافهایی که با اندازهگیریهای ما نشان داد شروع میشوند، نام ماشین و تعداد دفعات اجرا را ذکر میکنند. اعداد آنها از یک فایل خلاصه آمده است.
- یک Run نشاندهندهی یک فراخوانی
invokeیاstreamاست. یک Step نشاندهندهی یک سوپراستپ (Superstep) در حلقهی موتور LangGraph است. یک نوبت گفتوگو (Turn) شامل یک پیام انسانی و تمام فرایندهای منتهی به پاسخ است.
اجرای نخست در حالت آفلاین
برای کار با کیت به Python 3.13 نیاز دارید؛ چون دادهها با آن نسخه ثبت شدهاند. خود استک به Python 3.11 یا بالاتر نیاز دارد. از مسیر ریشهی این مستند، محیط مجازی (Virtual environment) را بسازید و بررسی اولیه را اجرا کنید:
python3.13 -m venv capture/.venv
capture/.venv/bin/pip install -r capture/requirements.txt
python3 capture/run.py --check
این دستور 19 سناریوی بدون نیاز به مدل را در پوشهای موقت دوباره اجرا کرده و هر فایل را با فایلهای متناظر در capture/out/ مقایسه میکند. همچنین بررسی میکند که نام مدل روی تکتک 36 فایلِ ثبتشده قید شده باشد. این بررسی علاوه بر این، ساختاری را که مستند بر آن متکی است (مانند انواع پیامها و نام ابزارها) چک میکند. سپس دادههای خلاصه در پوشهی lab را از روی خروجیهای خام دوباره بازسازی و مقایسه میکند. در این مرحله مدلی فراخوانی نمیشود؛ بنابراین برای سناریوهای ثبتشده، یک خط شامل skipped: چاپ میشود. با اجرای دستور python3 capture/run.py --check --live در شرایطی که Ollama روی سیستم شما در حال اجراست، میتوانید آنها را مجدداً ضبط کنید.
این همان سناریوی شرحدادهشده در بخش 1.3 است. در اینجا ایجنتی با یک ابزار و یک پرامپت سیستمی ساخته میشود و یک سؤال مطرح میکند:
def agent_run(cap):
m = llm()
agent = create_agent(m, tools=[add], system_prompt="You add numbers.")
out = agent.invoke(ASK)تابع سناریو از کیت. llm()، ابزار add و ASK از capture/common.py میآیند.
تابع llm() مدل ChatOllama را بر پایهی Qwen3 4B با تنظیمات فوق میسازد. مدل ابتدا ابزار add را با 2 و 3 فراخوانی کرد و سپس حاصلجمع را برگرداند. این اجرا با چهار پیام به پایان رسید:
"type": "HumanMessage",
"content": "What is 2 + 3?",
…
"type": "AIMessage",
"content": "",
…
"type": "ToolMessage",
"content": "5",
…
"type": "AIMessage",
"content": "2 + 3 = 5.",هر پیام فقط به نوع و محتوای آن خلاصه شده است. شناسهها و فراخوانی ابزار حذف شدهاند.
برای استفاده از مدلی دیگر، نام مدل را بهصورت رشتهای مانند "openai:gpt-4.1" بهجای m ارسال کنید و بستهی اختصاصی ارائهدهنده را نصب نمایید. در بخش 3.2 شیوهی پردازش این رشته نشان داده شده است.
ترتیب بخشها
بخش 1 به تصمیمگیری اختصاص دارد. این بخش هر پروژه و ادعاهای آن را در کنار نتایج ما قرار میدهد، بسترهای آزمایشی (Harnesses) را روی مجموعهوظایف مقایسه میکند و اجرای یک ایجنت را تا آخرین چکپوینت دنبال میکند. بخش 2 به سازوکار داخلی محیط اجرا (Runtime) میپردازد: سوپراستپها، کانالها، مسیر ثبت چکپوینت، وقفهها (Interrupt)، استریمها و افزایش حجم چکپوینت بر اساس ردگیری محاسبات (Trace) در اجراهای واقعی. بخش 3 استک را نصب میکند و مدل، پیامها، ابزارها و پرامپت را شرح میدهد.
بخش 4 به ایجنتی میپردازد که create_agent میسازد: گراف آن، خروجی ساختاریافته در هر ارائهدهنده، ابزارهای متعدد و میانافزارها. بخش 5 مفاهیم وضعیت، حافظه و اجرای پایدار (Durable Execution) را پوشش میدهد: استریمها، چکپوینترها، خرابیها، فضاهای ذخیرهسازی، رشتههای طولانی گفتوگو و سریالسازی دادهها. بخش 6 به جریان کاری (Flow) در LangGraph اختصاص دارد: وضعیت و کاهندهها (Reducer)، فراخوانیهای Send و Command، رابط کاربری تابعی، وقفهها، تأییدیهها، سفر در زمان، زیرگرافها و کنترلکنندههای خطا (Handler).
بخش 7 سیستمهای بازیابی (Retrieval)، ابزارهای MCP، فریمورک Deep Agents و ردگیری محاسبات با LangSmith را به هم متصل میکند. بخش 8 بهرهبرداری و عیبیابی را بررسی میکند: Agent Server، واسط کاربری Agent Chat، هزینه، امنیت، مهاجرت از نسخههای 0.x، علائم مشکلات، مانور شبیهسازی خرابی و محدودیتهای این نسخه. بخش 9 یک سرویس کامل آماده برای محیط عملیاتی را از ابتدا تا انتها با FastAPI، Postgres، تأییدیهها، اسپنهای OpenTelemetry، تزریق خطا، ارزیابیها و چند ورکر پیادهسازی میکند و آن را روی مدلهای Qwen3 4B، Qwen3 14B و Claude Haiku 5.5 اجرا مینماید. جدول زیر تمامی بخشها را نشان میدهد:
هر بخش با فهرست کوتاهی از اقدامات عملی به پایان میرسد. اگر امروز به پاسخی نیاز دارید، ابتدا همان نکات انتهایی را بخوانید و برای درک دلایل، بقیهی متن را مطالعه کنید.
برای درک عمیقتر مفاهیمی که در این مستند به کار رفتهاند، چهار درس دیگر ارائه شده است: درسهای ماشین وضعیت در LangGraph و گرافهای دارای وضعیت ساخت گراف را بر پایهی اصول بنیادین دنبال میکنند؛ درس سنجش تفاوتهای فریمورکهای ایجنت فریمورکها را با هم مقایسه میکند؛ و درس اجرای پایدار به تشریح چکپوینتها و بازپخش میپردازد. این مستند تماماً بر LangChain تمرکز دارد.
رنگها در تصاویر
هر رنگ در تمام تصاویر معنای یکسانی دارد:
در تصویر شیوهی رسم فلشها با استفاده از تعاملهای برگرفته از اجراهای واقعی نشان داده شده است. فلش ممتد یک فراخوانی و فلش خطچین با همان رنگ، پاسخ آن است. شش سبک دیگر هر یک نوع خاصی از رویداد را نشان میدهند و رنگ فلش با جدول بالا مطابقت دارد.
منابع: manual.json؛ capture/README.md, capture/run.py, capture/s_start.py, capture/common.py, capture/out/06-agent-run.txt, capture/out/03-tools.txt, capture/out/04-tool-errors.txt, capture/out/30-state-history-forks.txt, capture/out/42-langsmith.txt؛ capture/lab/, capture/lab/bench/summary-mac.json, capture/lab/bench/runs/cost-ledger.jsonl, capture/lab/prodapp-mac/runs/cost-ledger.jsonl؛ docs.langchain.com در commit مستندات به شناسهی 04d4d4a.