فریمورک LangChain ایجنت را میسازد، LangGraph آن را در قالب گرافی با چکپوینت اجرا میکند، LangSmith ردگیری محاسبات را ثبت میکند، و Deep Agents یک بستر آزمایشی (harness) به آن میافزاید؛ هرکدام در پکیجهایی با نسخهبندی خاص خودشان.
اگر روش ساخت ایجنت با LangChain را جستوجو کنید، با چهار نام محصول، سه دستور نصب و کدهایی مربوط به چهار سال گذشته روبهرو میشوید. در یک پاسخ AgentExecutor ایمپورت شده است، در دیگری create_react_agent، و در سومی create_deep_agent. هر سه نام هنوز در نسخهی قفلشده (pin) وجود دارند؛ با این تفاوت که فقط create_react_agent منسوخ شده و AgentExecutor همچنان در پکیج langchain-classic به حیاتش ادامه میدهد {{code libs/langchain/langchain_classic/agents/agent.py}}.
وقتی این بخش را تمام کنید، دقیقاً میدانید هریک از این چهار پروژه چه کاری انجام میدهد و در کدام پکیج قرار دارد. همچنین میتوانید ادعاهای اصلی هر پروژه را کنار نتایج آزمونهای ما بگذارید و بخشی را که آن ادعا را اثبات میکند، پیدا کنید.
چهار پروژه، چهار شمارهی نسخه
مستندات رسمی، ساختار این مجموعه را در چهار خط خلاصه میکند؛ یک خط برای هر پروژه {{docs oss/python/langgraph/overview}}:
- ابزار Deep Agents یک بستر آزمایشی است که برنامهریزی، سابایجنتها، ابزارهای کار با فایل و مدیریت زمینه (context) را به لایهی بالایی LangGraph اضافه میکند.
- فریمورک LangChain همان فریمورک اصلی است که رابطها و یکپارچهسازیهای مدلها، ابزارها و حلقهی ایجنت را فراهم میکند.
- محیط اجرای LangGraph وظیفهی اجرای پایدار (durable execution)، استریمینگ، بازبینی انسانی و ماندگاری دادهها را بر عهده دارد.
- پلتفرم LangSmith زیرساختی مستقل برای ردگیری محاسبات، ارزیابیها، پرامپتها و استقرارهاست و با هر فریمورکی کار میکند.
LangChain: فریمورک ساخت ایجنت، در پکیجهای langchain و langchain-core. پکیج langchain شامل تابع create_agent، میانافزارها (middleware) و تابع init_chat_model است. پکیج langchain-core پیامها، ابزارها، مدل پایهی چت و مدلهای ساختگی (fake models) را در بر دارد.
LangGraph: محیط اجرایی که ایجنت را بهصورت گرافی از گرهها اجرا میکند و در پکیج langgraph قرار دارد. مواردی چون StateGraph، حلقهی اجرای آن، چکپوینتها، وقفهها و استریمینگ درون این پکیج هستند.
LangSmith: پلتفرم میزبان برای ردگیری محاسبات، ارزیابیها، پرامپتها و استقرارها، همراه با پکیج کلاینت آن یعنی langsmith. سرویس Agent Server که گراف را پشت یک رابط برنامهنویسی HTTP اجرا میکند، متعلق به LangSmith است.
Deep Agents: بستری آزمایشی ساختهشده بر پایهی create_agent در پکیج deepagents. این ابزار مواردی مانند ابزارهای کار با فایل، سابایجنتها و خلاصهسازی را به ایجنت اضافه میکند.
این چهار مجموعه پکیج شمارهنسخهی مشترکی ندارند. در نسخهی آزمودهشده در این متن، پکیج langchain نسخهی 1.5.0، پکیج langchain-core نسخهی 1.8.0، پکیج langgraph نسخهی 1.2.22، پکیج deepagents نسخهی 0.7.38 و پکیج langsmith نسخهی 0.14.17 هستند. عبارتی مثل «LangChain 1.5» اگر نام دقیق پکیج را نیاورد مبهم است؛ زیرا طبق تاریخچهی انتشار در PyPI، پیشتر خود langchain-core یک انتشار 1.5.0 جداگانه داشته است. تصویر لایهی مربوط به هر پکیج را نشان میدهد.
این لایهها در یک ایجنت کامپایلشده کاملاً مشخصاند. خروجی create_agent شیئی از جنس CompiledStateGraph از ماژول langgraph.graph.state است که گرههای model و tools را دارد:
[
"__start__",
"model",
"tools",
"__end__"
]
…
type langgraph.graph.state.CompiledStateGraphخلاصهشده به فهرست گرهها و خط نوع داده. یالها، متن Mermaid و کانفیگ حذف شدهاند.
پکیج langsmith جزو وابستگیهای langchain-core است و همراه با هر ایجنتی نصب میشود {{code libs/core/pyproject.toml}}. ایجنت تا زمانی که متغیر محیطیِ فعالسازی ردگیری محاسبات روشن نشود، هیچ دادهای ارسال نمیکند {{code langsmith/utils.py}}. فقط دو بخش از langsmith بدون این متغیر داده میفرستند: تابع evaluate و پلاگین pytest؛ همانطور که در بخش 7.7 نشان دادهایم. در بستر آزمایش و ثبت دادههای ما، متغیر LANGSMITH_TRACING=false تنظیم شده و درخت اجرای LangSmith صرفاً درون حافظه ساخته میشود.
استانداردهای ارائهشده در این مجموعه
مجموعهی LangChain پنج بخش را با نامها و ساختارهای ثابت استاندارد میکند:
- یک فرمت پیام واحد: کلاسهای
SystemMessage،HumanMessage،AIMessageوToolMessageهمراه با بلوکهای محتوایی استاندارد میان تمام سرویسدهندگان. این بخش را در بخش 3.3 میبینید. - یک رابط ابزار واحد: هر تابعِ دارای نکتههای نوع (type hints) به ابزاری با اسکیمای JSON تبدیل میشود. اسکیماهایی را که مدل دریافت میکند در بخش 3.4 آوردهایم.
- یک حلقهی ایجنت واحد: تابع
create_agentگرافی میسازد که مدل را صدا میزند، ابزارهای درخواستی مدل را اجرا میکند و وقتی مدل ابزاری نخواهد، متوقف میشود. در بخش 1.3 یک دور اجرای آن را دنبال میکنیم. - یک رابط چکپوینت واحد: چکپوینتر وضعیت گراف را بعد از هر گام درون حافظه، SQLite یا Postgres ذخیره میکند.
- یک مجموعهی مشخص از حالتهای استریم: نامهایی مثل
updates،values،messages،customو چهار حالت دیگر مشخص میکنند خروجی استریم در هر گام چه دادهای تولید میکند.
مواردی که تعیین آنها با شماست
مدل و پکیج آن
فریمورک LangChain بهتنهایی هیچ مدلی را صدا نمیزند. باید پکیج ارائهدهنده را جداگانه نصب کنید؛ مثلاً langchain-openai یا langchain-ollama، و شیء مدل یا نام رشتهای آن را پاس بدهید. هر پکیج ارائهدهنده نسخه و تنظیمات پیشفرض تلاش مجدد (retry) خودش را دارد. در بخش 3.2 تعداد دفعات تلاش مجدد یکی از آنها را میشماریم.
ماندگاری دادهها
ایجنت هیچ گفتوگویی را ذخیره نمیکند، مگر اینکه یک چکپوینتر به آن پاس بدهید. یادداشتهای انتشار نسخهی v1 میگویند گفتوگوها از طریق چکپوینتهای داخلی بهخودیخود میان نشستهای مختلف باقی میمانند {{docs oss/python/releases/langchain-v1}}. اما صفحهی مستندات مربوط به ایجنتها میگوید که یک رشته گفتوگو فقط با چکپوینتر تاریخچهاش را نگه میدارد؛ پارامتری که در اجرای محلی باید خودتان پاس بدهید {{docs oss/python/langchain/agents}}. کدهای منبع نیز مستندات ایجنت را تأیید میکنند: مقدار پیشفرض پارامتر checkpointer در create_agent برابر با None است {{code langchain/agents/factory.py}}. روی سرویس Agent Server، خودِ سرور چکپوینتر را فراهم میکند.
عوارض جانبی که دو بار اجرا میشوند
وجود چکپوینتر قابلیت ادامهی اجرا (resume) را فراهم میکند، اما تضمین نمیکند فراخوانی ابزار دقیقاً یک بار رخ دهد. ابزاری که قبل از کرش کردن اجرا شده، ممکن است بعد از راهاندازی دوباره هم اجرا شود؛ بنابراین امن کردن این فرآیند بر عهدهی خود ابزار است.
ما این رفتار را سنجیدیم: روی سیستم Mac با گرافی سهگرهای که گره میانیاش خطی را به یک فایل اضافه میکرد، آزمایشی انجام دادیم. توقف ناگهانی (kill) را در پنج نقطهی مختلف، برای سه حالت پایداری و دو ذخیرهساز، در 5 تکرار برای هر حالت بررسی کردیم. در 10 آزمون از 150 آزمون، نقطهی توقف اصلاً پیش نیامد. در 80 آزمون از 150 حالت، آن خط دو بار در فایل نوشته شد. اما با تعریف کلید یکتایی تراکنش در گره، نوشتن تکراری در 0 مورد از 150 آزمون رخ داد.
همین آزمایش را سنجیدیم: همین پنج نقطه را روی سرور میهمان x86 و با ایجنتی مبتنی بر create_agent و مدل Qwen3 4B که ابزارش تراکنش مالی در PostgreSQL ثبت میکرد اجرا کردیم. بدون کلید یکتایی، در 331 مورد از 560 اجرای متوقفشده، سفارش دو بار شارژ شد. با استفاده از کلید یکتایی بر اساس رشته گفتوگو و شناسهی سفارش، در 0 مورد از 140 آزمون شارژ مجدد اتفاق افتاد. در بخش 5.3 دادههای دقیق هر حالت و در بخش 2.3 مسیر اجرای کد را نشان میدهیم.
تلاش مجدد در فراخوانی مدل
دو لایه وظیفهی تلاش مجدد پس از شکست فراخوانی مدل را دارند: کلاینتِ پکیج ارائهدهنده، و ModelRetryMiddleware. این دو لایه در هم ضرب میشوند. بخش 3.2 نشان میدهد که برای یک فراخوانی مدل که هر دو لایهاش روی تنظیمات پیشفرض بودند، از طریق یک رله روبهروی Ollama در مجموع 9 تلاش انجام شد؛ درحالیکه ChatOllama بدون میانافزار فقط 1 بار تلاش کرد.
سرور
سرویس Agent Server که گراف را با صف وظایف پشت یک API تحت پروتکل HTTP اجرا میکند، جزئی از LangSmith است. دستور langgraph dev آن را بهصورت درونحافظهای و بدون نیاز به کلید روی سیستم شما راه میاندازد. اما اجرای کل این پشته با دستور langgraph up همراه با Postgres و Redis، برای ما بدون کلید API متعلق به LangSmith یا لایسنس معتبر اجرا نشد:
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.دو خط نخست پیام خطا.
ادعاهای پروژه در مقایسه با نتایج سنجش ما
پروژهی LangChain در مستندات و صفحات معرفی محصول ادعاهای قاطعی را مطرح کرده است که اغلب شرطی برای آنها ذکر نشده است. جدول زیر هر ادعا را در کنار نتیجهی آزمایشهای ما نشان میدهد.
ما همهی دادهها را سنجیدهایم: هر نتیجه در این جدول روی سیستم Mac یا سرور میهمان x86 به دست آمده یا توسط بستر آزمایش ما ذخیره شده است. در هر ردیف، مشخصات سیستم و تعداد آزمونها ثبت شده است. از آنجا که دو سیستم مشخصات متفاوتی دارند، اعداد یک سطر را با سطر دیگر مقایسه نکنید.
| ادعای پروژه | نتیجهی آزمون ما | بخش |
|---|---|---|
| فریمورک LangChain v1 پایهای متمرکز و آماده برای محیط عملیاتی است {{docs oss/python/releases/langchain-v1}} | ما رفتار کد را سنجیدیم، نه این عبارت را. یکی از قوانین سیاست انتشار خود پروژه نقض شد: پکیج langchain 1.5.0 در یک نسخهی فرعی (minor)، حداقل نسخهی Python را به 3.11 افزایش داد. |
3.1 |
| مدلهای چت در مواجهه با خطاهای شبکه، 429 و 5xx تا 6 بار فراخوانی ناموفق را دوباره تکرار میکنند {{docs oss/python/langchain/models}} | در نسخهی قفلشده برای ChatOpenAI از پکیج langchain-openai 1.8.0 چنین نبود: از طریق رله در برابر Ollama ابتدا 3 تلاش صورت گرفت و سپس خطا داد. برای ChatOllama فقط 1 تلاش بود. سرور میهمان x86 با 3 بار تکرار برای قطعی اتصال، پورت مسدود و مهلت زمانی (timeout). |
3.2 |
میانافزار ModelRetryMiddleware با تنظیمات پیشفرض خود مجموعاً 3 تلاش انجام میدهد {{docs oss/python/langchain/middleware/built-in}} |
تأیید شد: 3 تلاش با خاموش بودن تلاش مجدد کلاینت. با روشن ماندن مقدار پیشفرض کلاینت، مجموع لایهها به 9 تلاش رسید. سرور میهمان x86 با 3 بار اجرا برای هر حالت. | 3.2 |
از نسخهی langgraph 1.1.4، سقف پیشفرض بازگشت (recursion limit) برابر با 10,007 گام است {{docs oss/python/langgraph/graph-api}} |
برای StateGraph تأیید شد: ابزار آزمایشی دقیقاً در گام 10007 متوقف میشود. اما create_agent سقف اختصاصی 9999 را اعمال میکند. در اجرای یک ایجنت مبتنی بر Qwen3 4B روی سرور میهمان x86، سیستم 121 فراخوانی مدل بدون وقفه داشت تا اینکه اسکریپت پس از 1200 ثانیه متوقفش کرد. |
1.3 |
سقف پیشفرض بازگشت در Agent Server برابر با 10011 است {{docs langsmith/env-var-cloud}} |
دیده نشد. با اجرای langgraph dev، گرافی دارای حلقهی بیپایان در گام 10007 متوقف شد؛ آزمودهشده در سرور میهمان x86. |
8.1 |
| گفتوگوها بهخودیخود در طول نشستهای مختلف باقی میمانند {{docs oss/python/releases/langchain-v1}} | تنها در صورت ارسال چکپوینتر ممکن است. مقدار پیشفرض در create_agent همانطور که در صفحهی ایجنتها آمده، بدون چکپوینتر است. |
1.3 |
در حالت durability="sync"، فریمورک LangGraph هر چکپوینت را قبل از ادامهی اجرا ثبت میکند {{docs oss/python/langgraph/checkpointers}} |
فقط در مرز بین گامها صدق میکند. بدون کلید یکتایی، متوقف کردن سیستم بعد از گام ابزار در 0 مورد از 40 آزمون منجر به شارژ مجدد شد؛ اما توقف بلافاصله پس از بازگشت نتیجهی ابزار و پیش از ذخیرهسازی، در 24 مورد از 40 بار شارژ مجدد ثبت کرد. مدل Qwen3 4B روی سرور میهمان x86. | 5.3 |
در حالت durability="async"، کرش سیستم احتمال اندکی برای از دست رفتن چکپوینتها دارد {{docs oss/python/langgraph/checkpointers}} |
تأیید شد. بدون کلید یکتایی، توقف بعد از گام ابزار در 38 مورد از 40 آزمون منجر به شارژ دوباره شد. مدل Qwen3 4B روی سرور میهمان x86. | 5.3 |
پس از ادامهی اجرا، گرهای که interrupt() را صدا زده است از خط اولش دوباره اجرا میشود {{docs oss/python/langgraph/interrupts}} |
در بستر آزمایشی تأیید شد: کدهای قبل از دستور interrupt() دو بار اجرا شدند. |
6.4 |
| در بازپخش، گرهها دوباره از اول اجرا میشوند و از کش خوانده نمیشوند {{docs oss/python/langgraph/use-time-travel}} | در بستر آزمایشی تأیید شد: بازپخش از چکپوینتِ قبل از ابزار، خود ابزار را دوباره اجرا کرد. | 6.6 |
| خروجی ساختاریافته مستقیماً از حلقهی اصلی تولید میشود و نیازی به فراخوانی مدل اضافی ندارد {{docs oss/python/releases/langchain-v1}} | روی Claude درست کار میکند، اما روی Ollama در صورت داشتن ابزار با شکست مواجه میشود. در مدل Qwen3 4B با ابزارهای جستوجو، ToolStrategy در 39 مورد از 39 وظیفه هیچ شیئی برنگرداند و ProviderStrategy در 10 مورد از 10 آزمون خطا داد. یک فراخوانی استخراج اضافی روی هر دو ارائهدهنده جواب داد. سیستم Mac و API شرکت Anthropic. |
4.3 |
هر ورکر صف (queue worker) بهطور همزمان تا N_JOBS_PER_WORKER اجرا را پردازش میکند و مقدار پیشفرض آن 10 است {{docs langsmith/agent-server-scale}} |
در langgraph dev اینطور نیست و مقدار پیشفرض آن 1 است. اجرای 20 وظیفهی پسزمینه (هرکدام 2 ثانیه) با مقدار 1 وظیفه حدود 41.0 ثانیه طول کشید و با تنظیم آن روی 10 به 5.1 ثانیه رسید. با مدل Qwen3 4B روی پردازنده، 10 اجرای ایجنت در پسزمینه با مقدار 1 وظیفه 47.1 ثانیه و با 10 وظیفه 44.4 ثانیه زمان برد؛ چون مدل در هر لحظه فقط یک فراخوانی را پردازش میکرد. سرور میهمان x86، هر حالت با یک دور اجرا. |
8.1 |
| صف وظایف Postgres در Agent Server هر وظیفه را دقیقاً یک بار اجرا میکند {{docs langsmith/deploy-standalone-server}} | در ویرایش بعدی بررسی خواهد شد. سرور کامل به لایسنس نیاز دارد. آزمایشهای ما روی خود کتابخانه هیچ تضمینی برای عوارض جانبی دقیقا یکباره نشان نداد: در 80 مورد از 150 آزمون، نوشتن دوباره رخ داد که در 10 موردِ آن سیستم اصلاً کرش نکرده بود. | 8.8 |
| سرور Agent Server در هر دو حالت استقرار، قطعیهای کوتاهمدت Redis یا Postgres را تاب میآورد {{docs langsmith/cloud-platform-features}} | در ویرایش بعدی بررسی میشود؛ به همان دلیل. | 8.8 |
| اجرای متوقفشده روی یک ورکرِ دچار وقفه، از آخرین چکپوینت خود ادامه مییابد {{docs langsmith/agent-server}} | در ویرایش بعدی بررسی میشود؛ به همان دلیل. | 8.8 |
| سرویس Redis هیچ دادهای از کاربر یا روند اجرا نگه نمیدارد {{docs langsmith/agent-server}} | در ویرایش بعدی بررسی میشود؛ به همان دلیل. | 8.8 |
| صفحهی محصول LangChain میگوید که این فریمورک روی محیطی پایدار با قابلیت ماندگاری و چکپوینتگیری داخلی اجرا میشود {{site langchain.com/langchain}} | چکپوینتگیری فقط وقتی داخلی است که خودتان چکپوینتر را پاس بدهید؛ همانطور که در بالا بررسی شد. | 1.3 |
پنج مورد از ادعاها با آزمایشهای ما دقیقاً همخوانی داشتند. چهار مورد مشروط به شرایطی بودند که در مستندات گفته نشده بود: ارائهی چکپوینتر از سمت شما، نقطهی وقوع کرش، یا ارائهدهندهی مدل. چهار ادعا هم در نسخهی قفلشده تطابق نداشتند: تعداد دفعات تلاش مجدد، سقف بازگشت در سرور، تعداد پیشفرض وظایف همزمان، و قاعدهی حداقل نسخهی پایتون در سیاست انتشار. چهار مورد دیگر نیز به سرور کامل Agent Server نیاز دارند و در بخش 8.8 همراه با آزمایشهای برنامهریزیشده برای نسخهی بعدی فهرست شدهاند.
سه مورد از این نتایج، رویکرد توسعهی شما را تغییر میدهند: تعداد تلاشهای مجدد پکیج ارائهدهندهی خود را بشمارید؛ تمام عوارض جانبی را برای اجرای دوباره امن کنید؛ و خروجی ساختاریافته را حتماً روی ارائهدهندهی خود همراه با ابزارهای فعال بسنجید.
چه زمانی این ابزار مناسب کار شما نیست؟
فریمورک LangChain مناسب ایجنتهایی است که در قالب یک حلقه ابزارها را صدا میزنند و به توقف، استریمینگ، یا ادامهی اجرا نیاز دارند. البته استفاده از آن، مقداری زمان اجرای پایتون به ازای هر فراخوانی مدل و مقداری فضای دیسک تحمیل میکند.
ما این سربار را سنجیدیم: هر دوی این موارد را روی Mac اندازه گرفتیم. در یک اجرای واقعی مدل Qwen3 4B با سه فراخوانی مدل، create_agent فقط 15.6 میلیثانیه به اجرای 1.8 ثانیهای اضافه کرد؛ یعنی تقریباً 5 میلیثانیه به ازای هر فراخوانی (در میان 40 اجرای جابهجاشده). نصب تر و تمیز langchain در کنار langchain-openai شامل 44 پکیج با حجم 54,312 کیلوبایت بود؛ درحالیکه خود openai بهتنهایی تنها 14 پکیج با حجم 26,356 کیلوبایت داشت. زمان نصب و زمان ایمپورتها در بخش 3.1 آورده شده است.
اگر برنامهی شما فقط یک مدل را بدون ابزار و بدون وضعیت صدا میزند، SDK خودِ ارائهدهنده با کدی بسیار کمتر دقیقاً همان کار را انجام میدهد.
منابع: مستندات docs.langchain.com در commit شمارهی 04d4d4a از مستندات (بخشهای oss/python/langgraph/overview، oss/python/releases/langchain-v1، oss/python/langchain/agents، oss/python/langchain/models، oss/python/langchain/middleware/built-in، oss/python/langgraph/graph-api، oss/python/langgraph/checkpointers، oss/python/langgraph/interrupts، oss/python/langgraph/use-time-travel، langsmith/env-var-cloud، langsmith/agent-server-scale، langsmith/deploy-standalone-server، langsmith/cloud-platform-features، langsmith/agent-server)؛ capture/out/00-versions.txt، capture/out/05-agent-graph.txt، capture/out/07-structured-output.txt، capture/out/30-state-history-forks.txt، capture/out/32-interrupt-resume.txt، capture/out/38-recursion-limit.txt، capture/out/42-langsmith.txt؛ فایلهای خلاصه capture/lab/summary/crash-resume-mac.json، capture/lab/summary/retries-x86.json، capture/lab/summary/recursion-mac.json، capture/lab/summary/recursion-x86.json، capture/lab/summary/overhead-mac-real.json، capture/lab/summary/agent-server-x86.json، capture/lab/summary/agent-server-x86-real.json، capture/lab/summary/install-size-mac.json، capture/lab/T15-agent-server-x86/10-up-license-excerpt.txt، capture/lab/summary/crash-resume-x86.json، capture/lab/T02-crash-resume-x86/10-summary.txt، capture/lab/bench/summary-mac.json، capture/lab/bench/runs/structured.jsonl؛ فایلهای کد libs/langchain_v1/langchain/agents/factory.py، libs/core/pyproject.toml، libs/langchain/langchain_classic/agents/agent.py در langchain==1.5.0؛ فایل libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py در langgraph 1.2.22؛ فایل src/langsmith/utils.py در langsmith v0.14.17؛ صفحهی معرفی محصول www.langchain.com/langchain، مشاهدهشده در 2026-11-14.