راهنمای عملی

LangChain 101

ساخت، اجرا، پایداری داده‌ها و دیباگ ایجنت‌ها با LangChain 1.5، LangGraph 1.2 و Deep Agents 0.7، همراه با پاسخی مستند برای هر تصمیم

  • نسخه‌ی سنجیده‌شده: LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0
  • ۷۱ بخش

چگونگی تبدیل مدل، ابزارها و یک پرامپت به یک ایجنت توسط پشته پایتونی LangChain، و زمان نیاز واقعی به آن. مجموعه‌ای از وظایف همراه با اعتبارسنج‌های وضعیت، حلقه ساده، create_agent، LangGraph و Deep Agents را روی مدل‌های محلی و Claude مقایسه می‌کند. ردگیری محاسبات در اجراهای واقعی، سازوکار داخلی محیط اجرا را نشان می‌دهد و یک سرویس FastAPI با Postgres و تأییدیه‌ها آن را در محیط عملیاتی اجرا می‌کند. تمام نمونه‌کدها برگرفته از خروجی واقعی یک اجرا با langchain 1.5.0، langchain-core 1.8.0، langgraph 1.2.22 و deepagents 0.7.38 است. تمام اعداد اندازه‌گیری‌شده حاصل ثبت اجرای یک مدل واقعی هستند.

شروع از بخش ۱٫۱

بعد از این راهنما می‌توانید

  • تصمیم‌گیری برای انتخاب LangChain، LangGraph یا Deep Agents برای یک ایجنت بر اساس کیفیت، زمان و هزینه اندازه‌گیری‌شده.
  • نصب پشته از روی یک فایل قفل در پایتون 3.11 یا بالاتر و تعیین بسته مربوط به هر import.
  • ساخت ایجنت با create_agent و پیش‌بینی هر فراخوانی مدل، فراخوانی ابزار، سوپراستپ و چک‌پوینت در طول اجرا.
  • انتخاب روش خروجی ساختاریافته و مجموعه‌ای از میان‌افزارها برای ارائه‌دهنده خود، و پیش‌بینی ترتیب اجرای هوک‌های آن‌ها.
  • استریمینگ اجرای ایجنت در حالت مورد نیاز، و حفظ مکالمه در طول نوبت‌های گفت‌وگو و راه‌اندازی‌های مجدد با چک‌پوینتر.
  • متوقف کردن اجرا جهت دریافت تأیید انسانی، ازسرگیری آن و مشخص‌کردن بخش‌هایی از کد که هنگام ازسرگیری دوباره اجرا می‌شوند.
  • شمارش دفعات تلاش در هر لایه تکرار، و ایمن‌سازی اثر جانبی هنگام بازپخش ناشی از کرش.
  • اتصال ابزارهای MCP، بازیاب، Deep Agents و ردگیری محاسبات در LangSmith، و یافتن ریشه خرابی از روی متن پیام خطا.
  • سرویس‌دهی ایجنت از طریق FastAPI با Postgres، تأییدیه‌ها، اسپن‌ها و ارزیابی‌ها، و تعیین منابع لازم بر اساس سرور مدل.
یک فراخوانی، دو اجرای مدل، یک اجرای ابزار
One invoke, two model calls, one tool call An isometric drawing of one create_agent run in one Python process. Above, on a LangChain layer, sit your code as a violet terminal, the chat model as a plum tower, and the tool add as a green unit. Below, the CompiledStateGraph from create_agent is an indigo shell with the LangGraph mark. It holds the model and tools nodes and the messages channel, drawn as four sheets. Your code calls invoke with What is 2 + 3? Model call 1 returns an AIMessage with the tool call add(a=2, b=3). The tools node runs add and returns a ToolMessage of 5. Model call 2 returns 2 + 3 = 5. The graph puts 5 checkpoints in InMemorySaver, steps -1 to 3, and the last has no next node. Off to the right, LangSmith is a dashed tower that gets 7 runs only when tracing is on. On the Mac, Apple M1 Max, with Qwen3 4B, create_agent spent 37.62 ms per run outside the model against 25.11 ms for a plain openai loop. ONE AGENT RUN · LANGCHAIN 1.5.0 · LANGGRAPH 1.2.22 · PYTHON 3.13 your code agent.invoke What is 2 + 3? 2 + 3 = 5. chat model call 1: tool_call add(a=2, b=3) call 2: 2 + 3 = 5. LangSmith outside the process POST 7, PATCH 7 tool add @tool, bound to the model LangChain model and tool objects CompiledStateGraph the Pregel loop from create_agent model tools messages HumanMessage AIMessage ToolMessage 5 AIMessage InMemorySaver thread memory-thread step -1 next __start__ step 0 next model step 1 next tools step 2 next model step 3 next () one Python process MEASURED ON THE MAC · APPLE M1 MAX outside the model: create_agent 37.62 ms per run, plain openai loop 25.11 ms +15.62 ms in the same round; with InMemorySaver 37.64 ms medians of 40 runs each, Qwen3 4B, a two-tool task with three model calls per run 1 invoke 2 call 1 3 add(a=2, b=3) ToolMessage 5 4 call 2 5 put 6 returns 7 7 runs, tracing on
یک بار اجرای متد `invoke` ایجنت، پرسش `What is 2 + 3?` را با دو بار فراخوانی مدل و یک بار اجرای ابزار `add` پاسخ می‌دهد. کلاس `InMemorySaver` پنج چک‌پوینت (گام‌های 1- تا 3) را ذخیره می‌کند و آخرین مورد، نود بعدی ندارد. با فعال بودن ردگیری محاسبات، هفت اجرا در LangSmith ثبت می‌شود. روی مک با مدل Qwen3 4B، تابع `create_agent` به ازای هر اجرا 37.6 میلی‌ثانیه خارج از مدل پردازش داشت، در حالی که این زمان برای یک حلقه ساده `openai` برابر 25.1 میلی‌ثانیه بود. برگرفته از capture/out/00-versions.txt، capture/out/05-agent-graph.txt، capture/out/06-agent-run.txt، capture/out/28-checkpoint-memory.txt، capture/out/30-state-history-forks.txt، capture/out/42-langsmith.txt و capture/lab/summary/overhead-mac-real.json.

این مستند سازوکار استک پایتونی 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 است. در اینجا ایجنتی با یک ابزار و یک پرامپت سیستمی ساخته می‌شود و یک سؤال مطرح می‌کند:

ایجنتِ اجرای اول capture/s_start.py
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 فراخوانی کرد و سپس حاصل‌جمع را برگرداند. این اجرا با چهار پیام به پایان رسید:

پیام‌ها در پایان اجرای اول capture/out/06-agent-run.txt
    "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 تمرکز دارد.

رنگ‌ها در تصاویر

هر رنگ در تمام تصاویر معنای یکسانی دارد:

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

راهنمای خواندن نمودار توالی در این کتابچههر سبک فلش نشان‌دهنده‌ی یک نوع تبادل است و تمام برچسب‌ها نام‌ها، پیام‌ها یا شمارش‌های واقعی از کیت ضبط هستند.
راهنمای خواندن نمودار توالی در این کتابچه شش خط عمر: کد شما، گراف ایجنت از create_agent، مدل چت Qwen3 4B روی Ollama، یک ابزار، چک‌پوینتر، و LangSmith بیرون از فرایند. هشت ردیف شماره‌دار از هشت سبک فلش استفاده می‌کنند: invoke با «2 + 3 چند می‌شود؟» به صورت فراخوانی با خط پیوسته تیره، پرامپت سیستم «شما اعداد را جمع می‌زنید.» به صورت فراخوانی مدل با خط پیوسته بنفش، فراخوانی ابزار add با a=2 و b=3 به صورت پاسخ با خط‌چین تیره، چک‌پوینت گام 1 به صورت نوشتن پایدار با خط پیوسته سبزآبی، حالت بعدی tools به صورت تغییر وضعیت با خط‌چین کهربایی، مقدار استریم سفارشی lookup A-17 به صورت استریم با نقطه‌چین نیلی، هفت درخواست POST /runs به صورت اثر بیرونی با خط‌چین زیتونی، و خطای RuntimeError disk on fire به صورت شکست با خط‌چین سرخ. کد شما agent.invoke گراف ایجنت create_agent مدل چت Qwen3 4B ابزار add, flaky_disk چک‌پوینتر InMemorySaver LangSmith بیرونی 1 invoke: 2 + 3 چند می‌شود؟ فراخوانی · خط پیوسته تیره 2 سیستم: شما اعداد را جمع می‌زنید. فراخوانی مدل · خط پیوسته بنفش 3 tool_calls: add(a=2, b=3) پاسخ · خط‌چین تیره 4 چک‌پوینت گام 1 نوشتن پایدار · خط پیوسته سبزآبی 5 بعدی: tools تغییر وضعیت · خط‌چین کهربایی 6 سفارشی: جستجوی A-17 جریان · نقطه‌چین نیلی 7 POST /runs، 7 بار اثر جانبی بیرونی · خط‌چین زیتونی 8 RuntimeError: آتش‌سوزی دیسک خطا · خط‌چین سرخ
هر ردیف شماره‌دار را از ابتدای فلش تا نوک آن بخوانید. یادداشت زیر هر برچسب، نام سبک آن را مشخص می‌کند. برگرفته از 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.

منابع: 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.

فهرست راهنما

بخش ۱: تصمیم‌گیری

سه بستر آزمایشی در 60 وظیفه از 60 وظیفه محلی اجراهای یکسانی ارائه دادند و Claude تمام وظایف را پاس کرد؛ پس بستر آزمایشی را بر اساس پایداری داده، استریمینگ و تأییدیه‌ها انتخاب کنید.

  1. 1.1چهارگانه‌ی LangChain، LangGraph، LangSmith و Deep Agents
  2. 1.2آیا به LangChain نیاز دارید؟ مقایسه‌ی چهار بستر آزمایشی روی یک مجموعه وظیفه
  3. 1.3یک دور اجرای create_agent، از invoke تا آخرین چک‌پوینت

بخش ۳: مدل‌ها، پیام‌ها و ابزارها

بسته ارائه‌دهنده بخش عمده قابلیت‌های ایجنت را مشخص می‌کند؛ از آنجا که در آزمون‌های ما ChatOllama پارامتر tool_choice را نادیده گرفت، پیش از اتکا به مقادیر پیش‌فرض، هر بسته را تست کنید.

  1. 3.1نصب و نقشه‌ی توزیع پکیج‌ها
  2. 3.2تابع init_chat_model و پروفایل مدل‌ها
  3. 3.3پیام‌ها و بلوک‌های محتوا
  4. 3.4ابزارها، ToolRuntime و خطاهای ابزار
  5. 3.5پرامپت سیستمی