بخش 1.3 · تصمیم‌گیری

یک دور اجرای create_agent، از invoke تا آخرین چک‌پوینت

One create_agent run, from invoke to the last checkpoint

فهرست مطالب
  1. روند اجرا
  2. مدل چه چیزی دریافت کرد؟
  3. گام‌به‌گام
  4. چک‌پوینت‌ها
  5. استریم کردن همان اجرا
  6. ردگیری محاسبات
  7. سقف بازگشت

یک‌بار فراخوانی invoke روی یک ایجنتِ create_agent، چهار گامِ گراف را طی می‌کند، دو بار مدل و یک بار ابزار را صدا می‌زند و با داشتن یک چک‌پوینتر، پنج چک‌پوینت ذخیره می‌کند.

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

در پایان این بخش، می‌توانید نام هر گام از یک دور اجرای ایجنت و وضعیت (state) پس از آن را مشخص کنید. همچنین متوجه می‌شوید که یک چک‌پوینتر در هر گام چه چیزهایی را ذخیره می‌کند و ردگیری محاسبات (trace) چه داده‌هایی را به ثبت می‌رساند.

روند اجرا

ایجنتی که در اجرای اول دیدیم، یک ابزار به نام add و پرامپت سیستمی You add numbers. داشت. مدل آن Qwen3 4B روی Ollama بود. این ایجنت ابتدا add را با 2 و 3 صدا زد و سپس پاسخ نهایی را داد. وضعیت برنامه در پایان اجرا به این صورت است:

وضعیت نهایی یک اجرا capture/out/06-agent-run.txt
  {
    "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) هر فراخوانی را ثبت می‌کند. مدل دو بار اجرا شد و در هر دو بار، ابتدا پرامپت سیستمی و سپس همان ابزار متصل‌شده را تحویل گرفت:

دو فراخوانی مدل capture/out/06-agent-run.txt
    "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 توضیح می‌دهیم که چرا پرامپت درون وضعیت ذخیره نمی‌شود.

گام‌به‌گام

تصویر روند اجرا را نشان می‌دهد. شماره‌های این فهرست با سطرهای تصویر هم‌خوانی دارند.

یک اجرای create_agent، گام‌به‌گامنود مدل دو بار و نود ابزارها یک بار اجرا می‌شود، و چک‌پوینتر وضعیت را بعد از ورودی و پس از هر یک از چهار گام ذخیره می‌کند.
یک اجرای create_agent، گام‌به‌گام پنج خط عمر زیر طرح‌های کوچک: کد شما به صورت ترمینال، نود model، مدل چت، نود tools، و چک‌پوینتر به صورت استوانه. ستون ششم پیام‌های درون هر چک‌پوینت را به صورت نشان‌هایی نمایش می‌دهد. شش مرحله شماره‌گذاری‌شده که با فهرست متن مطابقت دارد: 1، چک‌پوینت ورودی در گام -1 بدون پیام و بعدی __start__. 2، چک‌پوینت در گام 0 با پیام انسانی و بعدی model. 3، نود model مدل چت را با پرامپت سیستم «You add numbers.» و پیام انسانی فراخوانی می‌کند، یک فراخوانی ابزار add با 2 و 3 دریافت می‌کند و گام 1 را با بعدی tools ذخیره می‌کند. 4، نود model فراخوانی ابزار را به نود tools می‌فرستد که گام 2 را با ToolMessage برای <uuid-3> و بعدی model ذخیره می‌کند. 5، فراخوانی دوم مدل 4 پیام را دریافت کرده و پاسخ می‌دهد «2 + 3 = 5.». 6، چک‌پوینت در گام 3 دارای 4 پیام و بدون نود بعدی است، و invoke آن‌ها را برمی‌گرداند. کد شما agent.invoke نود model model chat model agent نود tools add checkpointer InMemorySaver STATE.MESSAGES در هر چک‌پوینت put، گام -1 next: __start__ خالی 1 put، گام 0 بعدی: model H 2 فراخوانی 1: 2 پیام tool_calls: add(2, 3) put، گام 1 بعدی: tools H AI 3 Send: add, <uuid-3> put، گام 2: ToolMessage 5 بعدی: model H AI T 4 فراخوانی 2: 4 پیام 2 + 3 = 5. 5 put، گام 3 بعدی: هیچ H AI T AI 4 پیام 6 H human AI AIMessage T ToolMessage پررنگ: جدید در این گام
سطرها را از بالا به پایین بخوانید. هر پیکان سبزآبی یک چک‌پوینت به همراه شماره‌ی گام آن است. یادداشت کهربایی زیر هر چک‌پوینت نودی است که در مرحله بعد اجرا می‌شود. نشان‌های سمت راست پیام‌های موجود در هر چک‌پوینت هستند و نشان پررنگ در آن گام جدید است. برگرفته از capture/out/06-agent-run.txt، capture/out/05-agent-graph.txt و capture/out/30-state-history-forks.txt.
  1. متد invoke ورودی را روی گراف قرار می‌دهد. با وجود چک‌پوینتر، LangGraph چک‌پوینت ورودی را در گام 1- ذخیره می‌کند.
  2. گره __start__ پیام کاربر را در messages می‌نویسد. چک‌پوینت گام 0 مشخص می‌کند که گره بعدی model است.
  3. گره model پرامپت سیستمی را اضافه می‌کند، ابزارها را متصل می‌سازد و مدل را فرا می‌خواند. مدل با یک فراخوانی ابزار پاسخ می‌دهد. چک‌پوینت گام 1 نشان می‌دهد گره بعدی tools است.
  4. گره tools تابع add(a=2, b=3) را اجرا می‌کند و یک ToolMessage می‌افزاید که tool_call_id آن همان شناسه‌ی فراخوانی است. چک‌پوینت گام 2 می‌گوید گره بعدی model است.
  5. گره model دوباره مدل را با هر سه پیام صدا می‌زند. مدل با متن پاسخ می‌دهد و فراخوانی ابزاری در کار نیست.
  6. یالِ بعد از model می‌بیند که فراخوانی ابزاری وجود ندارد، پس به __end__ می‌رود. چک‌پوینت گام 3 هیچ گره بعدی ندارد و invoke وضعیت را برمی‌گرداند.

یال‌های گراف کامپایل‌شده هم دقیقاً همین را نشان می‌دهند. دو یالِ خروجی از model شرطی هستند و فراخوانی‌های ابزار تعیین می‌کنند مسیر به کدام سمت برود:

یال‌های گراف ایجنت capture/out/05-agent-graph.txt
[
  "__start__ -> model",
  "model -> __end__ (conditional)",
  "model -> tools (conditional)",
  "tools -> model (conditional)"
]

گرافی که هیچ ابزاری ندارد، گره tools هم ندارد. این گراف شامل __start__، model و __end__ است و تنها یک بار مدل را فرا می‌خواند.

تصویر گراف این ایجنت را بر اساس متن Mermaid خروجیِ گراف کامپایل‌شده رسم کرده است. در بخش 4.1 یاد می‌گیرید که چطور نمودار گراف‌های خودتان را رسم کنید.

گراف ایجنت در این اجرایک یال ساده به model وارد می‌شود و سه یال شرطی از model و tools خارج می‌شوند، بنابراین اجرا مسیر خود را در زمان اجرا انتخاب می‌کند.
گراف ایجنت در این اجرا گراف کامپایل‌شده‌ی create_agent با یک ابزار، رسم‌شده از خروجی draw_mermaid آن. این گراف 4 نود دارد: __start__، model، tools و __end__. یک یال ساده از __start__ به model می‌رود. سه یال شرطی از model به tools، از model به __end__، و از tools به model برمی‌گردند. نود tools ابزار add را فهرست می‌کند. گراف کامپایل‌شده 4 نود، 1 یال ساده، 3 شرطی __start__ model tools __tools = add __end__ یال ساده یال شرطی، انتخاب در زمان اجرا
از __start__ در بالا بخوانید. پیکان‌های توپر یال‌های ساده و پیکان‌های خط‌چین کهربایی یال‌های شرطی هستند. نود tools تک ابزار خود را فهرست می‌کند. برگرفته از capture/out/48-draw-agent.txt.

چک‌پوینت‌ها

چک‌پوینت: وضعیت ذخیره‌شده‌ی یک رشته‌ی گفت‌وگو (thread) پس از یک گام، به‌همراه شماره‌ی گام، گره‌های بعدی و شناسه‌ی چک‌پوینت قبلی.

در اجرای بالا چک‌پوینتری وجود نداشت. کیت آموزشی ما همین ساختار ایجنت را با InMemorySaver در دو سناریوی دیگر اجرا می‌کند. در اولی سؤال What is 2 + 3? پرسیده می‌شود و سپس سؤال دومی در همان رشته‌ی گفت‌وگو مطرح می‌شود. پس از هر دو نوبت گفت‌وگو (turn)، رشته دارای 8 چک‌پوینت بود که آخرینِ آن‌ها گام 6 محسوب می‌شد:

ترد پس از دو نوبت گفت‌وگو capture/out/28-checkpoint-memory.txt
  "step": 6,
  "source": "loop",
…
8 checkpoints

خلاصه شده به گام آخرین چک‌پوینت و تعداد.

نوبت اول، گام‌های 1- تا 3 یعنی پنج چک‌پوینت را ذخیره کرد. نوبت دوم، گام‌های 4 تا 6 را ذخیره کرد. این نوبت تنها یک بار مدل را صدا زد؛ چون مدل بدون نیاز به ابزار پاسخ داد.

سناریوی دیگر از یک ابزار charge می‌خواهد مبلغ 10 را کسر کند و سپس تاریخچه را از جدیدترین به قدیمی‌ترین می‌خواند. گام‌های این سناریو دقیقاً و یک‌به‌یک با فهرست بالا مطابقت دارد:

تاریخچه‌ی یک نوبت گفت‌وگو، از جدیدترین capture/out/30-state-history-forks.txt
  "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) برمی‌گرداند که کلید آن، نام گره اجراشده است:

تکه‌های یک استریم بدون حالت مشخص capture/out/21-stream-updates-values.txt
chunk 0 keys:
[
  "model"
]

chunk 1 keys:
[
  "tools"
]

chunk 2 keys:
[
  "model"
]

بخش پایانی فایل. هر تکه به کلیدهایش خلاصه شده است.

سه تکه داده برای اجرای سه گره. گام __start__ هیچ تکه داده‌ای برنمی‌گرداند. بخش 5 سایر حالت‌های استریم را نشان می‌دهد.

ردگیری محاسبات

وقتی ردگیری محاسبات (tracing) روشن باشد، LangChain برای هر بخش از کار یک گزارش اجرا به LangSmith می‌فرستد. کیت آموزشی ما همین ایجنت را در یک سیستم ردگیری محلی قرار می‌دهد و داده‌هایی را که کلاینت قرار بود ارسال کند، ثبت می‌کند:

اجراهای یک نوبت گردش ایجنت ردگیری‌شده capture/out/42-langsmith.txt
  "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 است و فراخوانی‌های مدل و ابزار در نقش برگ‌های این درخت قرار دارند.

اجراهای یک نوبت گردش ایجنت ردگیری‌شدهیک نوبت ردگیری‌شده درختی از اجراهاست، با یک اجرای chain برای هر نود گراف و یک برگ برای هر فراخوانی مدل و فراخوانی ابزار.
اجراهای یک نوبت گردش ایجنت ردگیری‌شده یک درخت تورفته از 8 اجرا به ترتیبی که آغاز شده‌اند، هر کدام در یک سطر: chain agent_turn، chain LangGraph، chain model، llm ChatOllama، chain tools، tool add، chain model، llm ChatOllama. ریشه‌ی agent_turn تابع قابل ردگیری کیت است، درون tracing_context با حالت محلی فعال، و در حافظه باقی ماند. هر یک از 7 اجرای زیر آن یک پیکان خط‌چین زیتونی به یک لاین کلاینت در سمت راست دارد، زیرا کلاینت هنگام شروع اجرا یک POST /runs و هنگام پایان آن یک PATCH دریافت کرد: در مجموع 7 POST و 7 PATCH. هر نود گراف یک اجرای chain است، دو فراخوانی مدل برگ‌های llm هستند، و فراخوانی ابزار یک برگ tool است. کلاینت ثبت هر درخواست درخت اجرا، به ترتیب آغاز اجراها نام در بالای نوع اجرا agent_turn اجرای chain kept in memory: tracing_context(enabled='local') LangGraph اجرای chain POST، سپس PATCH model اجرای chain ChatOllama اجرای llm tools اجرای chain add اجرای tool model اجرای chain ChatOllama اجرای llm 7 اجرا زیر ریشه، 7 درخواست POST /runs و 7 درخواست PATCH در کلاینت. یک نود گراف فراخوانی مدل فراخوانی ابزار
از ریشه در بالا بخوانید. هر جعبه یک اجرا است، با نام آن در بالای نوع اجرا. ریشه‌ی بنفش در حافظه ماند، و کلاینت هفت اجرای زیر آن را دریافت کرد. برگ‌های آلبالویی فراخوانی‌های مدل و برگ سبز فراخوانی ابزار است. برگرفته از capture/out/42-langsmith.txt.

سقف بازگشت

هر گام در گراف، یک واحد از سقف بازگشت (recursion limit) اجرای برنامه کم می‌کند. تابع create_agent این محدودیت را روی گراف کامپایل‌شده برابر 9999 قرار می‌دهد که کمی کمتر از حد پیش‌فرض LangGraph برای سایر گراف‌ها (یعنی 10007) است:

کانفیگ روی ایجنت کامپایل‌شده capture/out/05-agent-graph.txt
{
  "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.