یکبار فراخوانی
invokeروی یک ایجنتِcreate_agent، چهار گامِ گراف را طی میکند، دو بار مدل و یک بار ابزار را صدا میزند و با داشتن یک چکپوینتر، پنج چکپوینت ذخیره میکند.
شما با یک سؤال agent.invoke را صدا میزنید و در پاسخ، چهار پیام تحویل میگیرید. این خروجی شبیه یک تبادل تکمرحلهای با مدل به نظر میرسد؛ اما پشت صحنه، یک گراف چهار گام برداشته، مدل دو بار اجرا شده و یک ابزار هم به کار افتاده است. اگر بعداً اجرای برنامه به خطایی بخورد، نام یکی از همین گامها در پیام خطا میآید؛ بنابراین باید ترتیب اجرای آنها را دقیق بشناسید.
در پایان این بخش، میتوانید نام هر گام از یک دور اجرای ایجنت و وضعیت (state) پس از آن را مشخص کنید. همچنین متوجه میشوید که یک چکپوینتر در هر گام چه چیزهایی را ذخیره میکند و ردگیری محاسبات (trace) چه دادههایی را به ثبت میرساند.
روند اجرا
ایجنتی که در اجرای اول دیدیم، یک ابزار به نام add و پرامپت سیستمی You add numbers. داشت. مدل آن Qwen3 4B روی Ollama بود. این ایجنت ابتدا add را با 2 و 3 صدا زد و سپس پاسخ نهایی را داد. وضعیت برنامه در پایان اجرا به این صورت است:
{
"type": "HumanMessage",
"content": "What is 2 + 3?",
"id": "<uuid-1>"
},
{
"type": "AIMessage",
"content": "",
"id": "lc_run--<uuid-2>-0",
"tool_calls": [
{
"name": "add",
"args": {
"a": 2,
"b": 3
},
"id": "<uuid-3>",
"type": "tool_call"
}
],
…
{
"type": "ToolMessage",
"content": "5",
"name": "add",
"id": "<uuid-4>",
"tool_call_id": "<uuid-3>",
"status": "success"
},
{
"type": "AIMessage",
"content": "2 + 3 = 5.",
"id": "lc_run--<uuid-5>-0",فهرست کلیدها و متادیتای هر پاسخ حذف شدهاند. هر چهار پیام نمایش داده شدهاند.
این وضعیت فقط یک کلید دارد: messages. پرامپت سیستمی داخل آن نیست. شناسهی دو پاسخِ مدل با lc_run-- شروع میشود، چون LangChain شناسهی اجرای هر مدل را به خروجی آن اختصاص میدهد. پیامهای کاربر و ابزار هم وقتی گراف آنها را اضافه میکند، یک UUID معمولی میگیرند. شناسهی فراخوانی ابزار (tool call id) نیز یک UUID است، چون ChatOllama برای هر فراخوانی یک شناسه میسازد. علاوه بر این، هر پاسخ حاوی response_metadata و usage_metadata از طرف Ollama است که تعداد توکنهای مصرفشده در آن فراخوانی را نشان میدهد.
مدل چه چیزی دریافت کرد؟
کیت آموزشی ما با یک کنترلکننده (callback handler) هر فراخوانی را ثبت میکند. مدل دو بار اجرا شد و در هر دو بار، ابتدا پرامپت سیستمی و سپس همان ابزار متصلشده را تحویل گرفت:
"call": 1,
"messages": [
"system: You add numbers.",
"human: What is 2 + 3?"
],
"tools": [
"add"
]
…
"call": 2,
"messages": [
"system: You add numbers.",
"human: What is 2 + 3?",
"ai: calls add",
"tool: 5"
],خلاصه شده به پیامها و ابزارهای متصلشده. برچسب مدل حذف شده است.
به این ترتیب، ایجنت در هر فراخوانی کل گفتوگو را میفرستد و پرامپت سیستمی را هم به ابتدای هر درخواست اضافه میکند. در بخش 3.5 توضیح میدهیم که چرا پرامپت درون وضعیت ذخیره نمیشود.
گامبهگام
تصویر روند اجرا را نشان میدهد. شمارههای این فهرست با سطرهای تصویر همخوانی دارند.
- متد
invokeورودی را روی گراف قرار میدهد. با وجود چکپوینتر، LangGraph چکپوینت ورودی را در گام1-ذخیره میکند. - گره
__start__پیام کاربر را درmessagesمینویسد. چکپوینت گام0مشخص میکند که گره بعدیmodelاست. - گره
modelپرامپت سیستمی را اضافه میکند، ابزارها را متصل میسازد و مدل را فرا میخواند. مدل با یک فراخوانی ابزار پاسخ میدهد. چکپوینت گام1نشان میدهد گره بعدیtoolsاست. - گره
toolsتابعadd(a=2, b=3)را اجرا میکند و یکToolMessageمیافزاید کهtool_call_idآن همان شناسهی فراخوانی است. چکپوینت گام2میگوید گره بعدیmodelاست. - گره
modelدوباره مدل را با هر سه پیام صدا میزند. مدل با متن پاسخ میدهد و فراخوانی ابزاری در کار نیست. - یالِ بعد از
modelمیبیند که فراخوانی ابزاری وجود ندارد، پس به__end__میرود. چکپوینت گام3هیچ گره بعدی ندارد وinvokeوضعیت را برمیگرداند.
یالهای گراف کامپایلشده هم دقیقاً همین را نشان میدهند. دو یالِ خروجی از model شرطی هستند و فراخوانیهای ابزار تعیین میکنند مسیر به کدام سمت برود:
[
"__start__ -> model",
"model -> __end__ (conditional)",
"model -> tools (conditional)",
"tools -> model (conditional)"
]گرافی که هیچ ابزاری ندارد، گره tools هم ندارد. این گراف شامل __start__، model و __end__ است و تنها یک بار مدل را فرا میخواند.
تصویر گراف این ایجنت را بر اساس متن Mermaid خروجیِ گراف کامپایلشده رسم کرده است. در بخش 4.1 یاد میگیرید که چطور نمودار گرافهای خودتان را رسم کنید.
چکپوینتها
چکپوینت: وضعیت ذخیرهشدهی یک رشتهی گفتوگو (thread) پس از یک گام، بههمراه شمارهی گام، گرههای بعدی و شناسهی چکپوینت قبلی.
در اجرای بالا چکپوینتری وجود نداشت. کیت آموزشی ما همین ساختار ایجنت را با InMemorySaver در دو سناریوی دیگر اجرا میکند. در اولی سؤال What is 2 + 3? پرسیده میشود و سپس سؤال دومی در همان رشتهی گفتوگو مطرح میشود. پس از هر دو نوبت گفتوگو (turn)، رشته دارای 8 چکپوینت بود که آخرینِ آنها گام 6 محسوب میشد:
"step": 6,
"source": "loop",
…
8 checkpointsخلاصه شده به گام آخرین چکپوینت و تعداد.
نوبت اول، گامهای 1- تا 3 یعنی پنج چکپوینت را ذخیره کرد. نوبت دوم، گامهای 4 تا 6 را ذخیره کرد. این نوبت تنها یک بار مدل را صدا زد؛ چون مدل بدون نیاز به ابزار پاسخ داد.
سناریوی دیگر از یک ابزار charge میخواهد مبلغ 10 را کسر کند و سپس تاریخچه را از جدیدترین به قدیمیترین میخواند. گامهای این سناریو دقیقاً و یکبهیک با فهرست بالا مطابقت دارد:
"step": 3,
"source": "loop",
"next": [],
…
"step": 2,
"source": "loop",
"next": [
"model"
],
…
"step": 1,
"source": "loop",
"next": [
"tools"
],
…
"step": 0,
"source": "loop",
"next": [
"model"
],
…
"step": -1,
"source": "input",
"next": [
"__start__"
],خلاصه شده به گام، مبدأ، و نودهای بعدی هر چکپوینت. شناسهها و پیامها حذف شدهاند.
چکپوینتی که مقدار next آن نام یک گره را نشان میدهد، نقطهای است که میتوان اجرا را در آن متوقف کرد و بعداً ادامه داد. بخش 5 میگوید هر چکپوینت در چه زمانی نوشته میشود و اگر برنامهای بین دو چکپوینت متوقف شود، چه بخشهایی دوباره تکرار خواهند شد.
استریم کردن همان اجرا
هر گراف وضعیت کامپایلشده (StateGraph) بهطور پیشفرض از حالت استریم updates استفاده میکند، و ایجنت هم یکی از همین گرافهاست {{code libs/langgraph/langgraph/graph/state.py}}. بنابراین فراخوانی agent.stream(input) بدون تعیین حالت، برای هر گام یک تکه داده (chunk) برمیگرداند که کلید آن، نام گره اجراشده است:
chunk 0 keys:
[
"model"
]
chunk 1 keys:
[
"tools"
]
chunk 2 keys:
[
"model"
]بخش پایانی فایل. هر تکه به کلیدهایش خلاصه شده است.
سه تکه داده برای اجرای سه گره. گام __start__ هیچ تکه دادهای برنمیگرداند. بخش 5 سایر حالتهای استریم را نشان میدهد.
ردگیری محاسبات
وقتی ردگیری محاسبات (tracing) روشن باشد، LangChain برای هر بخش از کار یک گزارش اجرا به LangSmith میفرستد. کیت آموزشی ما همین ایجنت را در یک سیستم ردگیری محلی قرار میدهد و دادههایی را که کلاینت قرار بود ارسال کند، ثبت میکند:
"PATCH /runs/<run-id>": 7,
"POST /runs": 7
}
chain agent_turn
chain LangGraph
chain model
llm ChatOllama
chain tools
tool add
chain model
llm ChatOllamaخلاصه شده به تعداد درخواستها و درخت اجراها، که در خطوط 82 تا 99 فایل قرار دارند.
این درخت شامل هشت اجرا است. مورد بیرونی یعنی agent_turn همان تابع traceable کیت ما است که در حافظه باقی ماند. هفت اجرای LangChain زیر آن، هرکدام هنگام شروع یک درخواست POST و هنگام پایان یک درخواست PATCH دریافت کردند. تصویر این درخت را نشان میدهد. هر گره گراف یک اجرای chain است و فراخوانیهای مدل و ابزار در نقش برگهای این درخت قرار دارند.
سقف بازگشت
هر گام در گراف، یک واحد از سقف بازگشت (recursion limit) اجرای برنامه کم میکند. تابع create_agent این محدودیت را روی گراف کامپایلشده برابر 9999 قرار میدهد که کمی کمتر از حد پیشفرض LangGraph برای سایر گرافها (یعنی 10007) است:
{
"recursion_limit": 9999,
"metadata": {
"ls_integration": "langchain_create_agent"
},
"configurable": {}
}کانفیگ گراف کامپایلشده، از همان فایل.
مدلی که مدام درخواست ابزار بدهد و متوقف نشود، تا رسیدن به این سقف به کارش ادامه میدهد. کیت آموزشی به مدل Qwen3 4B دستور داد تا با استفاده از add مدام رو به بالا بشمارد و اصلاً متوقف نشود. با تنظیم recursion_limit=6 در پیکربندی، اجرا بعد از سه بار فراخوانی مدل و دو بار فراخوانی ابزار با این خطا متوقف شد: GraphRecursionError: Recursion limit of 6 reached without hitting a stop condition.
ما این موضوع را اندازه گرفتیم: رفتار یک ایجنتِ گرفتار در حلقه را روی یک سیستم مهمان در سرور x86 تست کردیم. مدل Qwen3 4B پیش از آنکه اسکریپت پس از 1200 ثانیه متوقفش کند، 121 بار مدل را فراخواند و هیچ نشانهای از توقف نشان نداد. اما تنظیم recursion_limit=25 در هر 3 اجرای آزمایشی، توانست آن را بعد از 13 بار فراخوانی مدل متوقف کند. همیشه سقفی متناسب با وظیفه (task) خود تعیین کنید؛ زیرا گرفتار شدن در حلقه، به ازای تکتک فراخوانیهای مدل برایتان هزینه میتراشد.
منابع: capture/out/06-agent-run.txt، capture/out/05-agent-graph.txt، capture/out/48-draw-agent.txt، capture/out/28-checkpoint-memory.txt، capture/out/30-state-history-forks.txt، capture/out/21-stream-updates-values.txt، capture/out/46-recursion-agent.txt، capture/out/42-langsmith.txt؛ capture/lab/summary/recursion-x86.json، capture/lab/T17-claims-x86/01-claims.jsonl، capture/lab/T17-claims-x86/02-nolimit.jsonl، capture/lab/summary/recursion-mac.json، capture/lab/T17-claims-mac/01-recursion-limit.jsonl؛ libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0، libs/langgraph/langgraph/graph/state.py و libs/langgraph/langgraph/_internal/_config.py در langgraph 1.2.22.