بخش 3.4 · مدل‌ها، پیام‌ها و ابزارها

ابزارها، ToolRuntime و خطاهای ابزار

Tools, ToolRuntime, and tool errors

فهرست مطالب
  1. اسکیمایی که مدل می‌بیند
  2. مفهوم ToolRuntime
  3. خطاهای ابزار
  4. نام ابزارها و شناسه‌های فراخوانی ابزار
  5. یک ToolMessage برای هر فراخوانی ابزار

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

فرض کنید به ایجنت ابزاری برای خواندن فایل می‌دهید؛ دیسک از کار می‌افتد و کل اجرا با خطا متوقف می‌شود (Raise). بار دیگر مدل به‌جای عدد صحیح، رشته می‌فرستد؛ این بار اجرا متوقف نمی‌شود و گفت‌وگو با یک پیام خطا ادامه می‌یابد. یک ایجنت واحد با دو شکست برخوردی کاملاً متفاوت داشته است.

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

اسکیمایی که مدل می‌بیند

ابزار (Tool): تابعی که با @tool پوشانده شده و دارای نام، توضیحات و یک اسکیمای JSON برای آرگومان‌های خود است.

کیت آموزشی تابع add را با دو آرگومان تایپ‌شده و یک داک‌استرینگ (Docstring) تعریف می‌کند:

ابزار add capture/common.py
@tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

دکوراتور @tool اسکیما را بر اساس راهنماهای نوع (Type hints) می‌سازد و توضیحات را از داک‌استرینگ برمی‌دارد. مدلی که فراخوانی می‌شود، چنین ساختاری دریافت می‌کند:

اسکیمای add capture/out/03-tools.txt
{
  "description": "Add two integers.",
  "properties": {
    "a": {
      "title": "A",
      "type": "integer"
    },
    "b": {
      "title": "B",
      "type": "integer"
    }
  },
  "required": [
    "a",
    "b"
  ],
  "title": "add",
  "type": "object"
}

ابزاری بدون راهنماهای نوع، اسکیمای به‌دردبخوری دریافت نمی‌کند. صفحه‌ی مستندات ابزارها می‌گوید که استفاده از راهنماهای نوع الزامی است، چون اسکیمای ورودی را تعریف می‌کنند {{docs oss/python/langchain/tools}}. داک‌استرینگ را برای مدل بنویسید، چون این تنها توضیحی است که مدل دریافت می‌کند.

مفهوم ToolRuntime

محیط اجرای ابزار (ToolRuntime): نوعی پارامتر که وضعیت (State)، بافتار (Context)، حافظه (Store)، نویسنده‌ی جریان (Stream writer) و شناسه‌ی فراخوانی ابزار جاری را در اختیار ابزار می‌گذارد.

پارامتری با نام runtime و نوع ToolRuntime توسط خود ایجنت مقداردهی می‌شود و مدل هرگز آن را نمی‌بیند. مستندات رسمی نیز همین را می‌گوید {{docs oss/python/langchain/tools}}. ابزار lookup_order در کیت آموزشی دو پارامتر دارد، اما در اسکیمای آن فقط یک پارامتر دیده می‌شود:

تابع lookup_order و اسکیمای آن capture/out/03-tools.txt
lookup_order.args:
[
  "order_id"
]

tool_call_schema:
{
  "description": "Look up an order by its id.",
  "properties": {
    "order_id": {
      "title": "Order Id",
      "type": "string"
    }
  },

فهرست آرگومان‌های ابزار، و سپس اسکیمایی که مدل می‌بیند.

نام‌های runtime و config رزرو شده‌اند. صفحه‌ی مستندات ابزارها هشدار می‌دهد که استفاده از هر یک از این دو نام برای آرگومان‌های ابزار، در زمان اجرا (Run time) باعث بروز خطا می‌شود {{docs oss/python/langchain/tools}}.

درون یک ایجنت، lookup_order مقادیر runtime.context و runtime.tool_call_id را می‌خواند و مقداری را با runtime.stream_writer می‌نویسد. این مقدار در حالت جریان (Stream mode) از نوع custom و پیش از ToolMessage از راه می‌رسد:

کلاس ToolRuntime داخل create_agent capture/out/43-tool-runtime-agent.txt
custom:
{
  "lookup": "A-17"
}

updates tools:
[
  {
    "type": "ToolMessage",
    "content": "order A-17: shipped (asked by ada, tool_call_id=<uuid-2>)",

تکه (chunk) سفارشی و به‌روزرسانی ابزار. دو به‌روزرسانی مدل حذف شده‌اند.

باید runtime.stream_writer(value) را مستقیماً مانند یک تابع فراخوانی کنید. در مثال داک‌استرینگ ToolRuntime متد stream_writer.write(...) فراخوانی شده است {{code libs/prebuilt/langgraph/prebuilt/tool_node.py:1746}}. چنین متدی وجود ندارد، زیرا StreamWriter صرفاً یک شیء فراخوان‌پذیر (Callable) ساده است {{code libs/langgraph/langgraph/types.py}}. این راهنما این مغایرت را با عنوان تعارض D3 ثبت کرده است.

ابزاری که از ToolRuntime استفاده می‌کند، خارج از یک ایجنت قابل اجرا نیست. اگر آن را فقط با آرگومان‌های خودش صدا بزنید، به دلیل نبودن runtime خطای ValidationError رخ می‌دهد:

فراخوانی دستی یک ابزار ToolRuntime capture/out/03-tools.txt
lookup_order.invoke({'order_id': 'A-17'}):

raised pydantic_core._pydantic_core.ValidationError: 1 validation error for lookup_order
runtime
  Field required [type=missing, input_value={'order_id': 'A-17'}, input_type=dict]

خط راهنمای pydantic حذف شده است.

چنین ابزاری را درون یک ایجنت آزمایش کنید؛ درست مانند کاری که کیت آموزشی با Qwen3 4B انجام می‌دهد.

خطاهای ابزار

خطای ابزار (Tool error): شکستی که هنگام اجرای یک فراخوانی ابزار توسط ایجنت رخ می‌دهد. نوع آن تعیین می‌کند که اجرا با خطا متوقف می‌شود یا ادامه می‌یابد.

ایجنت ابزارها را با یک ToolNode اجرا می‌کند. تابع create_agent از کنترل‌کننده‌ی خطای پیش‌فرض ToolNode بهره می‌برد؛ سازوکاری که فراخوانی نامعتبر را به پیام تبدیل کرده و بقیه‌ی استثناها را بالا می‌اندازد (Raise) {{code libs/prebuilt/langgraph/prebuilt/tool_node.py}}. تصویر چهار حالت کیت آموزشی را نشان می‌دهد.

تأثیر هر نوع خطای ابزار بر اجرای برنامهآرگومان‌های نامعتبر و نام ابزار ناشناخته به یک ToolMessage خطا تبدیل می‌شوند، و بروز استثنا داخل ابزار اجرا را متوقف می‌کند مگر اینکه میان‌افزار آن را تبدیل کند.
تأثیر هر نوع خطای ابزار بر اجرای برنامه چهار سطر، هر کدام از یک خطا در سمت چپ تا نتیجه‌ی آن در سمت راست. آرگومان‌های نامعتبر، مانند ارسال دستور شل به‌صورت شیء به جای رشته، تبدیل به یک ToolMessage با وضعیت error می‌شوند و مدل دوباره تلاش می‌کند. نام ابزار ناشناخته، مانند subtract از نسخه‌ی قبلی، تبدیل به ToolMessage با وضعیت error می‌شود و مدل متنی پاسخ می‌دهد. رخ دادن استثنا همراه با ToolErrorMiddleware تبدیل به ToolMessage با وضعیت error حاوی متن on_error می‌شود. رخ دادن استثنا بدون میان‌افزار، مانند RuntimeError disk on fire، از تابع invoke پرتاب شده و اجرا را متوقف می‌کند. نوع خطا آنچه اجرا دریافت می‌کند آرگومان‌های نامعتبر {'command': {'command': 'ls'}} ToolMessage، وضعیت error مدل دوباره تلاش می‌کند نام ناشناخته ابزار subtract، از استقرار قبلی ToolMessage، وضعیت error مدل متنی پاسخ می‌دهد استثنا، همراه میان‌افزار ToolErrorMiddleware ToolMessage، وضعیت error text from on_error استثنا، بدون میان‌افزار RuntimeError پرتاب خطا در invoke خرابی دیسک سه مورد اول به فراخوانی بعدی مدل می‌روند. مورد آخر اجرا را متوقف می‌کند.
هر سطر را از خطا در سمت چپ تا نتیجه در سمت راست بخوانید. سطرهای سبز به فراخوانی بعدی مدل ادامه می‌دهند و سطر صورتی در invoke استثنا پرتاب می‌کند. برگرفته از capture/out/04-tool-errors.txt و capture/out/19-mw-shell-files.txt.

آرگومان‌های نادرست به یک ToolMessage با وضعیت error تبدیل می‌شوند و مدل شانس دومی پیدا می‌کند. کیت آموزشی نتوانست Qwen3 4B را وادار به ارسال آرگومان نادرست برای add کند. وقتی محاسبه‌ی 2.5 + 3 از آن خواسته شد، مقادیر 2 و 3 را فرستاد و سپس به کاربر گفت این ابزار اعداد صحیح می‌گیرد. همچنین وقتی از آن خواسته شد بلندی صدای 0 تا 10 را روی 11 تنظیم کند، هیچ ابزاری را فراخوانی نکرد و گفت 10 بیشینه‌ی مجاز است.

آرگومان‌های نادرست از ابزار شل (Shell) در بخش 4.6 آمدند. مدل دستور را به‌جای رشته، در قالب یک شیء فرستاد؛ آن هم شش بار پیاپی:

مدل آرگومان‌های نامعتبر ارسال می‌کند capture/out/19-mw-shell-files.txt
    "content": "Error invoking tool 'shell' with kwargs {'command': {'command': 'ls'}} with error:\n command: Input should be a valid string\n Please fix the error and try again.",
    "name": "shell",
…
    "status": "error"

اولین ToolMessage از اجرایی که ls را درخواست کرد.

وقتی مدل همان اشتباه را تکرار می‌کند، شانس دوم کمکی نخواهد کرد؛ بنابراین محدودیت بازگشت (Recursion limit) یا سقف تعداد فراخوانی ابزار بگذارید.

یک مدل واقعی به‌ندرت نام ابزاری را می‌آورد که در اختیارش قرار نگرفته است. وقتی وجود ابزار فرضی subtract به Qwen3 4B گفته شد، add را با 5 و 3- فراخوانی کرد. نام ناشناخته معمولاً زمانی رخ می‌دهد که ابزارهای یک رشته گفت‌وگو (Thread) در حین کار تغییر کنند. کیت آموزشی ایجنتی را که subtract داشت متوقف کرد و سپس ترد را با ایجنتی ادامه داد که فقط add را داشت. فراخوانی ذخیره‌شده به این پیام خطا تبدیل شد: Error: subtract is not a valid tool, try one of [add]..

استثنای درون ابزار داستان دیگری دارد. بدون میان‌افزار (Middleware)، متد invoke خطای RuntimeError: disk on fire را بالا انداخت و اجرا به پایان رسید.

میان‌افزار ToolErrorMiddleware این استثنا را به یک پیام تبدیل می‌کند. تابع on_error آن متن را برمی‌گرداند و اجرا ادامه می‌یابد:

تبدیل استثنا به پیام توسط ToolErrorMiddleware capture/out/04-tool-errors.txt
    "type": "ToolMessage",
    "content": "RuntimeError in flaky_disk: disk on fire",
    "name": "flaky_disk",
    "id": "<uuid-11>",
    "tool_call_id": "<uuid-10>",
    "status": "error"

فقط ToolMessage.

اگر ToolErrorMiddleware() را بدون on_error بسازید، هنگام ساخت با خطای ValueError متوقف می‌شود. تلاش مجدد گزینه‌ی متفاوتی است: ToolRetryMiddleware ابزار را دوباره اجرا می‌کند و بخش 4 تعداد دفعات تلاش آن را می‌شمارد.

نام ابزارها و شناسه‌های فراخوانی ابزار

شناسه‌ی فراخوانی ابزار (Tool call id): شناسه‌ای که مدل به هر فراخوانی ابزار اختصاص می‌دهد و ToolMessage آن فراخوانی، در مسیر برگشت آن را با خود همراه دارد.

ما سه حالت را با Qwen3 4B سنجیدیم. حالت نام تکراری 3 بار روی سیستم‌عامل مهمانِ سرور x86 اجرا شد و در هر 3 اجرا نتیجه‌ی یکسانی داد. حالت تعداد فراخوانی، به ازای هر تعداد یک بار اجرا شد. حالت بدون شناسه هم یک استاب (Stub) روی Mac است که به ازای هر سناریو یک سطر خروجی دارد.

تعریف دو ابزار با نام یکسان خطایی در create_agent بالا نینداخت. دو ابزار safe_lookup و privileged_delete را که هر دو account_action نام داشتند پاس دادیم. ابزاری که در فهرست دیرتر آمده بود برنده شد: مدل تنها اسکیمای آن را دریافت کرد و هر فراخوانی فقط همان ابزار را اجرا کرد. با قرار گرفتن privileged_delete در جایگاه دوم، فراخوانی account_action ابزار privileged_delete را اجرا کرد.

در کار با یک مدل واقعی، انتخاب مدل از توضیحات ابزار دوم پیروی کرد. وقتی متن Delete an account. را دید، از اجرای جست‌وجو خودداری کرد و درخواست حذف را با privileged_delete انجام داد. این موضوع در ایشوی langgraph#7988 گزارش شده است {{issue langgraph#7988}}. به هر ابزار نامی یکتا بدهید.

سروری که فراخوانی‌های ابزار را بدون شناسه بفرستد، اجرای برنامه را از دو جهت خراب می‌کند. ما دو فراخوانی هم‌روند بدون شناسه را از یک استاب به ChatOpenAI و create_agent فرستادیم. با invoke و stream_mode="messages"، هر دو ابزار اجرا شدند و سپس اجرا خطای TypeError: Tool lookup returned unexpected type: <class 'str'> را بالا انداخت. بنابراین اثرات جانبی رخ دادند، ولی اجرا شکست خورد. در نسخه‌ی 3 از stream_events، هر شناسه به "" تبدیل شد، هر دو ابزار اجرا شدند و هر دو شیء ToolMessage شناسه‌ی "" را گرفتند. ایشوی langchain#40531 این تبدیل اجباری را گزارش کرده است {{issue langchain#40531}}.

هیچ مدل واقعی فراخوانی بدون شناسه تولید نکرد: Ollama 0.31.1 در هر دو مسیر شناسه می‌فرستد، بنابراین این سطرها از یک استاب روی Mac به دست آمده‌اند.

مدل Qwen3 4B در پاسخ به درخواست‌های 1، 2، 4، 8 و 16 فراخوانی، به ترتیب 2، 2، 4، 8 و 16 فراخوانی انجام داد. هر تعداد یک بار روی سیستم‌عامل مهمانِ سرور x86 اجرا شد. در هر دو مسیر، تک‌تک فراخوانی‌ها شناسه داشتند. این مسیرها ChatOllama و ChatOpenAI روی مسیر /v1 مربوط به Ollama بودند.

در نسخه‌ی 3، بخشی از فراخوانی ابزار که در آخرین تکه (Chunk) از استریم باشد از دست می‌رود. تکه‌ای با chunk_position="last" به‌جای بلوک‌های چانک، فراخوانی‌های ابزارِ پردازش‌شده را از content_blocks گزارش می‌دهد؛ آن هم فقط فراخوانی‌های دارای شناسه را {{code libs/core/langchain_core/messages/ai.py}}. تکه‌ای ناقص از آرگومان‌ها به‌تنهایی پردازش نمی‌شود، بنابراین chunks_to_events هیچ تغییر و تفاوتی (Delta) برای آن دریافت نمی‌کند {{code libs/core/langchain_core/language_models/_compat_bridge.py}}. در یک مدل ساختگی (چون هیچ مدل واقعی چنین چیزی تولید نمی‌کند)، فراخوانی دوم به یک فراخوانی نامعتبر تبدیل شد و یک ToolMessage خطا گرفت. بدون شناسه‌ها، یکی از آن دو فراخوانی اصلاً اجرا نشد.

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

یک ToolMessage برای هر فراخوانی ابزار

صفحه‌ی مستندات ابزارها می‌گوید هر فراخوانی ابزار در تاریخچه، نیازمند یک ToolMessage است که به آن پاسخ دهد {{docs oss/python/langchain/tools}}. ایجنت این قاعده را در تمام موارد بالا، از جمله در خطاها، برای شما حفظ می‌کند. کدی هم که پیام‌ها را ویرایش می‌کند — مثل کوتاه‌سازی (Trim) یا خلاصه‌سازی — باید این قاعده را رعایت کند.

منابع: capture/common.py، capture/s_start.py، capture/out/03-tools.txt، capture/out/43-tool-runtime-agent.txt، capture/out/04-tool-errors.txt، capture/out/19-mw-shell-files.txt؛ capture/lab/summary/parallel-tools-x86.json، capture/lab/T08-parallel-tools-x86/01-counts.jsonl، capture/lab/T08-parallel-tools-x86/02-raw-ollama.jsonl، capture/lab/T08-parallel-tools-x86/03-dupnames.jsonl، capture/lab/T08-parallel-tools-x86/t08_real.py؛ capture/lab/summary/parallel-tools-mac.json، capture/lab/T08-parallel-tools-mac/02-idless-and-dupnames.jsonl، capture/lab/T08-parallel-tools-mac/t08_ids.py؛ ایشوی langgraph#7988، ایشوی langchain#40531؛ فایل‌های libs/core/langchain_core/messages/ai.py و libs/core/langchain_core/language_models/_compat_bridge.py در langchain-core 1.8.0؛ docs.langchain.com در docs commit 04d4d4a بخش (oss/python/langchain/tools)؛ libs/prebuilt/langgraph/prebuilt/tool_node.py و libs/langgraph/langgraph/types.py در langgraph 1.2.22؛ libs/core/langchain_core/tools در langchain==1.5.0.

ترجمه‌ی فارسی Tools, ToolRuntime, and tool errors از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما