# فصل ۰۳ — `tool calling`: مدل تابعِ تو را صدا می‌زند

<div dir="rtl">

# فصل ۰۳ — `tool calling`: مدل تابعِ تو را صدا می‌زند

## در این فصل چه یاد می‌گیری

به حسابِ مدل نمی‌شود تکیه کرد. **این را دستِ‌کم نگیر:** «جریمهٔ ۵ ساعت تأخیرِ کتابِ مرجع چقدر است؟» جوابش در هیچ سندی نوشته نشده — باید ۵ را در ۶ ضرب کنی. و بدلِ ما که فقط استخراج می‌کند، حتی وقتی هر دو حقیقت جلوی چشمش است، **صفر از چهار** می‌گیرد. مدلِ واقعی این ضربِ ساده را احتمالاً درست می‌زند، ولی این را نمی‌شود به‌ش سپرد.

در این فصل به آن اجازه می‌دهیم **کار بخواهد**: تابعِ تو را نام ببرد و ورودی‌اش را پیشنهاد بدهد؛ **اجرا با کدِ توست.** همان چهار پرسش می‌شود **چهار از چهار**. و بعد سه راهِ خراب شدنِ این ماجرا را می‌بینیم که یکی‌شان را **هیچ اعتبارسنجی‌ای نمی‌گیرد**.

![یک دستِ ماشینی که ابزارِ درست را از تخته برمی‌دارد و به دستِ دیگری می‌دهد](/lesson-assets/t5-s03-tool-calling/prompt/01-image-hand-picks-tool.png)

آخر این فصل می‌توانی:

- ابزار را با `schema` تعریف کنی و به مدل معرفی کنی
- حلقهٔ «درخواست → اجرا → پاسخ» را کامل بنویسی
- ورودیِ پیشنهادیِ مدل را قبلِ اجرا از دروازه رد کنی
- بگویی چرا فهرستِ سفید تنها مرزِ امنیتیِ واقعی است

## قبل از شروع

**از فصل ۲:** `pydantic`، `Literal`، `Field` و `ValidationError`. اینجا همان‌ها از داده به **ورودیِ تابع** می‌روند.

**از فصل ۱:** `chat` و نقش‌های پیام. یک نقشِ چهارم هم اضافه می‌شود: `tool`.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/zharfa/term-5-llm-engineering/session-03-tool-calling.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. یک ابزار یعنی چه

**سه تکه دارد و هر سه لازم است:**

- **تابعِ واقعیِ پایتون** — چیزی که کار را می‌کند.
- **`schema`ی ورودی‌ها** — چه آرگومان‌هایی، از چه نوعی.
- **یک توضیح به زبانِ آدمیزاد** — که مدل از رویش تصمیم می‌گیرد **کِی** به دردش می‌خورد.

**تکهٔ سوم را دستِ‌کم نگیر.** آن توضیح، پرامپت است. بخشِ ۲ نشان می‌دهد چطور یک توضیحِ بد، ابزارِ سالم را عملاً نامرئی می‌کند.

</div>

```python
from typing import Literal

from pydantic import BaseModel, Field, ValidationError

LIMITS = {"عادی": (3, 14), "دانشجویی": (5, 21), "پژوهشی": (8, 30)}


def fa(number):
    """عدد را با ارقامِ فارسی برمی‌گرداند — ترجمه، سرِ مرزِ خروجی."""
    return str(number).translate(str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹"))


class LateBookArgs(BaseModel):
    days: int = Field(ge=0, le=365)


class LateReferenceArgs(BaseModel):
    hours: int = Field(ge=0, le=24)


class MaxLoanArgs(BaseModel):
    tier: Literal["عادی", "دانشجویی", "پژوهشی"]
    renewals: int = Field(ge=0, le=2)


class HoursArgs(BaseModel):
    day: Literal["شنبه", "پنجشنبه", "جمعه"]


def fine_for_late_book(a):
    return f"{fa(a.days)} روز تأخیرِ کتابِ عادی = {fa(2 * a.days)} امتیازِ منفی"


def fine_for_late_reference(a):
    return f"{fa(a.hours)} ساعت تأخیرِ کتابِ مرجع = {fa(6 * a.hours)} امتیازِ منفی"


def max_loan_days(a):
    total = LIMITS[a.tier][1] + 7 * a.renewals
    return f"عضو {a.tier} با {fa(a.renewals)} بار تمدید: {fa(total)} روز"


def hours_lookup(a):
    table = {"شنبه": "۸ تا ۲۰", "پنجشنبه": "۸ تا ۱۴", "جمعه": "تعطیل"}
    return f"ساعتِ کارِ {a.day}: {table[a.day]}"


TOOLS = [
    {"name": "fine_for_late_book", "run": fine_for_late_book, "args": LateBookArgs,
     "description": "جریمهٔ دیرکردِ یک کتابِ عادی را بر حسبِ امتیازِ منفی حساب می‌کند؛ ورودی تعدادِ روزِ تأخیر است",
     "parameters": {"type": "object", "properties": {
         "days": {"type": "integer", "description": "تعدادِ روزِ تأخیر"}}, "required": ["days"]}},
    {"name": "fine_for_late_reference", "run": fine_for_late_reference, "args": LateReferenceArgs,
     "description": "جریمهٔ دیرکردِ یک کتابِ مرجع در امانتِ کوتاه؛ ورودی تعدادِ ساعتِ تأخیر است",
     "parameters": {"type": "object", "properties": {
         "hours": {"type": "integer", "description": "تعدادِ ساعتِ تأخیر"}}, "required": ["hours"]}},
    {"name": "max_loan_days", "run": max_loan_days, "args": MaxLoanArgs,
     "description": "حداکثر روزی که عضو می‌تواند کتاب را نگه دارد، با در نظر گرفتنِ تمدید",
     "parameters": {"type": "object", "properties": {
         "tier": {"type": "string", "enum": ["عادی", "دانشجویی", "پژوهشی"]},
         "renewals": {"type": "integer", "description": "تعدادِ تمدید"}}, "required": ["tier", "renewals"]}},
    {"name": "hours_lookup", "run": hours_lookup, "args": HoursArgs,
     "description": "ساعتِ کارِ کتابخانه در یک روزِ هفته",
     "parameters": {"type": "object", "properties": {
         "day": {"type": "string", "enum": ["شنبه", "پنجشنبه", "جمعه"]}}, "required": ["day"]}},
]
BY_NAME = {t["name"]: t for t in TOOLS}

QUESTIONS = [
    "جریمهٔ ۱۰ روز تأخیر در بازگرداندنِ کتابِ عادی چند امتیاز است؟",
    "جریمهٔ ۵ ساعت تأخیر در بازگرداندنِ یک کتابِ مرجع چند امتیاز است؟",
    "عضو دانشجویی با ۲ بار تمدید چند روز فرصت دارد؟",
    "عضو پژوهشی با ۱ بار تمدید چند روز فرصت دارد؟",
]

reset_calls()
for q in QUESTIONS:
    call = chat([{"role": "user", "content": q}], tools=TOOLS)["tool_call"]
    print(f"{q[:40]:<42} → {call['name'] if call else '— هیچ ابزاری'}")
```

<div dir="rtl">

</div>

```text
جریمهٔ ۱۰ روز تأخیر در بازگرداندنِ کتابِ   → fine_for_late_book
جریمهٔ ۵ ساعت تأخیر در بازگرداندنِ یک کت   → fine_for_late_reference
عضو دانشجویی با ۲ بار تمدید چند روز فرصت   → — هیچ ابزاری
عضو پژوهشی با ۱ بار تمدید چند روز فرصت د   → — هیچ ابزاری
```

<div dir="rtl">

**دو تا از چهار تا.** دو پرسشِ آخر هیچ ابزاری نگرفتند — **در حالی که `max_loan_days` دقیقاً برای همین دو پرسش نوشته شده و در فهرست هم هست.**

**پس مشکل از داشتن یا نداشتنِ ابزار نیست.**

## ۲. توضیحِ ابزار، پرامپت است

</div>

```python
BY_NAME["max_loan_days"]["description"] = (
    "چند روز فرصت دارد: مدتِ امانتِ یک عضو با احتسابِ بار تمدید")

reset_calls()
for q in QUESTIONS:
    call = chat([{"role": "user", "content": q}], tools=TOOLS)["tool_call"]
    print(f"{q[:40]:<42} → {call['name'] if call else '— هیچ ابزاری'}")
```

<div dir="rtl">

</div>

```text
جریمهٔ ۱۰ روز تأخیر در بازگرداندنِ کتابِ   → fine_for_late_book
جریمهٔ ۵ ساعت تأخیر در بازگرداندنِ یک کت   → fine_for_late_reference
عضو دانشجویی با ۲ بار تمدید چند روز فرصت   → max_loan_days
عضو پژوهشی با ۱ بار تمدید چند روز فرصت د   → max_loan_days
```

<div dir="rtl">

**همان تابع، همان `schema`، همان پرسش‌ها — فقط توضیح عوض شد و ۲ از ۴ شد ۴ از ۴.**

توضیحِ اول تمیز و مؤدب بود: «حداکثر روزی که عضو می‌تواند کتاب را نگه دارد». توضیحِ دوم **زشت‌تر** است ولی عبارتی را دارد که کاربر واقعاً به‌کار می‌برد: «چند روز فرصت دارد».

> 📏 **اندازه بگیر:** **قاعده: توضیحِ ابزار را با کلماتِ کاربر بنویس، نه با کلماتِ مستنداتِ داخلی.** و مثلِ هر ادعای دیگری در این ترم، **این را هم اندازه بگیر**: چند پرسشِ نمونه بنویس، بشمار چند تا ابزارِ درست را انتخاب می‌کنند، توضیح را عوض کن، دوباره بشمار. **این ارزان‌ترین بهبودِ کلِ سامانه است** و اکثر تیم‌ها اصلاً امتحانش نمی‌کنند.

## ۳. خطِ پایه: بدونِ ابزار چه می‌شود

</div>

```python
CORPUS = "\n\n".join(d["text"] for d in DOCS)
SYSTEM = "تو دستیارِ کتابخانه‌ای. فقط از متنِ زیر جواب بده. اگر جواب در متن نیست بنویس: در سند نیست"

reset_calls()
without = []
for q in QUESTIONS:
    text = chat([{"role": "system", "content": SYSTEM},
                 {"role": "user", "content": CORPUS + "\n\n" + q}])["text"]
    without.append(text)
    print("  ", text[:60])
```

<div dir="rtl">

</div>

```text
   به‌ازای هر روز تأخیر در بازگرداندنِ کتابِ عادی ۲ امتیازِ منف
   به‌ازای هر روز تأخیر در بازگرداندنِ کتابِ عادی ۲ امتیازِ منف
   در سند نیست
   در سند نیست
```

<div dir="rtl">

**کلِ پیکره جلوی چشمش بود و هیچ‌کدام را نگرفت.**

دو تای اول **قانون** را برگرداندند به‌جای **جواب** — «هر روز ۲ امتیاز» درست است ولی پرسش «۱۰ روز چقدر؟» بود. دو تای آخر هم صادقانه گفتند نمی‌دانند.

**و این دقیقاً مرزی است که باید ببینی:** جواب در هیچ جمله‌ای نوشته نشده. **باید ساخته شود، از ترکیبِ دو حقیقت و یک ضرب.** بازیابیِ متن این را حل نمی‌کند — هرچقدر هم بازیابی‌ات خوب باشد.

## ۴. اجرای امن

</div>

```python
def call_tool(tool_call):
    """مرزِ امنیتی: فقط از فهرستِ سفید، و فقط بعد از اعتبارسنجی."""
    if tool_call["name"] not in BY_NAME:
        raise ValueError(f"ابزارِ ناشناخته: {tool_call['name']}")
    tool = BY_NAME[tool_call["name"]]
    checked = tool["args"](**tool_call["arguments"])
    return tool["run"](checked)


reset_calls()
for q in QUESTIONS:
    call = chat([{"role": "user", "content": q}], tools=TOOLS)["tool_call"]
    print("  ", call_tool(call))
```

<div dir="rtl">

</div>

```text
   ۱۰ روز تأخیرِ کتابِ عادی = ۲۰ امتیازِ منفی
   ۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
   عضو دانشجویی با ۲ بار تمدید: ۳۵ روز
   عضو پژوهشی با ۱ بار تمدید: ۳۷ روز
```

<div dir="rtl">

**این شش خط کوچک‌ترین تابعِ این ترم است و مهم‌ترینشان.** دو خطش دو دیوارِ جداگانه‌اند:

- **`if ... not in BY_NAME`** — فهرستِ سفید. **فقط ابزارهایی که خودت نوشته‌ای.**
- **`tool["args"](**...)`** — دروازهٔ فصلِ ۲، این بار روی آرگومان‌ها.

> ✅ **چک کن:** اگر به‌جای `BY_NAME[...]` وسوسه شدی `globals()[name]` یا `getattr(module, name)` بنویسی، **بایست.** آن‌وقت مدل می‌تواند نامِ **هر** تابعی را که در حافظه هست بگوید. `eval` و `exec` روی خروجیِ مدل هم همین‌طور. **این مرز جای خلاقیت نیست.**

## ۵. حلقهٔ کامل

</div>

```python
def answer_with_tools(question, verbose=False):
    messages = [{"role": "user", "content": question}]
    first = chat(messages, tools=TOOLS)
    if first["tool_call"] is None:
        return first["text"]
    result = call_tool(first["tool_call"])
    if verbose:
        print("   ۱) مدل خواست :", first["tool_call"])
        print("   ۲) کد اجرا کرد:", result)
    messages.append({"role": "tool", "name": first["tool_call"]["name"], "content": result})
    return chat(messages)["text"]          # این بار بدونِ ابزار: فقط جملهٔ نهایی را بساز


reset_calls()
print("   ۳) جوابِ نهایی:", answer_with_tools(QUESTIONS[1], verbose=True))
```

<div dir="rtl">

</div>

```text
   ۱) مدل خواست : {'name': 'fine_for_late_reference', 'arguments': {'hours': 5}}
   ۲) کد اجرا کرد: ۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
   ۳) جوابِ نهایی: ۵ ساعت تأخیرِ کتابِ مرجع = ۳۰ امتیازِ منفی
```

<div dir="rtl">

**سه گام، و مرز دقیقاً وسطِ گامِ اول و دوم است:**

- **۱)** **مدل تصمیم می‌گیرد** — کدام ابزار، با چه ورودی. **هیچ کاری نمی‌کند؛ فقط نام می‌برد.**
- **۲)** **کدِ تو اجرا می‌کند** — بعد از فهرستِ سفید و اعتبارسنجی.
- **۳)** **نتیجه با نقشِ `tool` برمی‌گردد** — همراهِ **نامِ ابزار** — و مدل جملهٔ نهایی را می‌سازد.

**آن `name` تزیینی نیست.** بدونش مدل نمی‌داند این نتیجه جوابِ کدام درخواست بود، و اگر چند ابزار پشتِ‌سرِ‌هم صدا زده شود **گم می‌شود و همان ابزار را دوباره می‌خواهد.** فصلِ ۷ که حلقه را باز می‌کند، دقیقاً روی همین بند می‌ایستد.

**و به تماسِ دوم دقت کن: `tools` را دیگر نفرستادیم.** یعنی صریح گفتیم «کارت تمام است، فقط جمله را بساز». **این حلقه عمداً یک‌مرحله‌ای است** — یک درخواست، یک اجرا، یک جواب. اگر ابزار را دوباره پیشنهاد کنی، مدل می‌تواند باز هم ابزار بخواهد و **حلقه‌ای باز می‌شود که خودش موضوعِ فصلِ ۷ است.**

**«مدل تصمیم می‌گیرد، کدِ تو اجرا می‌کند» شعار نیست، معماری است.** هر بار که این مرز را می‌شکنی، یک راهِ نفوذ باز کرده‌ای — و فصلِ ۹ نشان می‌دهد چطور یک **سند** می‌تواند همان تصمیم را بدزدد.

## ۶. حالا با عدد

</div>

```python
GOLD_ANSWERS = ["۲۰ امتیاز", "۳۰ امتیاز", "۳۵ روز", "۳۷ روز"]

reset_calls()
with_tools = [answer_with_tools(q) for q in QUESTIONS]
hit_without = sum(a in t for a, t in zip(GOLD_ANSWERS, without))
hit_with = sum(a in t for a, t in zip(GOLD_ANSWERS, with_tools))

print("بدونِ ابزار:", hit_without, "از ۴ درست")
print("با ابزار   :", hit_with, "از ۴ درست")
```

<div dir="rtl">

</div>

```text
بدونِ ابزار: 0 از ۴ درست
با ابزار   : 4 از ۴ درست
```

<div dir="rtl">

**صفر به چهار.** و این بهبود از هوشِ بیشترِ مدل نیامد — **از این آمد که کارِ حساب را به چیزی سپردیم که حساب بلد است.**

> 📏 **اندازه بگیر:** **قاعده‌ای که در فصلِ ۲ دیدی، اینجا شکلِ کامل‌ترش را می‌گیرد: هر چیزی که کد می‌تواند **حساب** کند یا **جست‌وجو** کند، ابزار شود.** مدل برای فهمیدنِ پرسش است و ساختنِ جملهٔ جواب. تاریخ و ارز و موجودی و نرخ — **هیچ‌کدام را از حافظهٔ مدل نپرس.** حافظه‌اش کهنه است و مطمئن هم به‌نظر می‌رسد.

## ۷. خرابیِ اول: ورودیِ بی‌معنا

</div>

```python
reset_calls()
vague = chat([{"role": "user", "content": "جریمهٔ تأخیر کتابِ مرجع چطور حساب می‌شود؟"}], tools=TOOLS)
print("مدل پیشنهاد داد:", vague["tool_call"])
try:
    call_tool(vague["tool_call"])
except ValidationError as error:
    problem = error.errors()[0]
    print("دروازه جلویش را گرفت →", problem["loc"], "|", problem["type"], "|", repr(problem["input"]))
```

<div dir="rtl">

</div>

```text
مدل پیشنهاد داد: {'name': 'fine_for_late_book', 'arguments': {'days': 'نامشخص'}}
دروازه جلویش را گرفت → ('days',) | int_parsing | 'نامشخص'
```

<div dir="rtl">

**پرسش هیچ عددی نداشت — «چطور حساب می‌شود؟» یک پرسشِ روش است، نه یک حساب.** ولی مدل به‌جای اینکه بگوید نمی‌دانم، **چیزی از خودش ساخت** و در آرگومان گذاشت.

**این رفتار واقعی است و باید انتظارش را داشته باشی:** مدل‌ها تمایل دارند فیلدِ اجباری را **پر کنند**، حتی وقتی داده‌ای برایش ندارند.

**و دقت کن دروازه کجا ایستاد:** قبل از اجرای تابع. اگر `fine_for_late_book` را بدونِ دروازه صدا می‌زدی، `2 * 'نامشخص'` هیچ خطایی نمی‌داد: پایتون رشته را دو بار تکرار می‌کند و تابع **بی‌صدا** «نامشخص روز تأخیرِ کتابِ عادی = نامشخصنامشخص امتیازِ منفی» برمی‌گرداند.

**و `error.errors()` را هم ببین:** به‌جای بریدنِ متنِ خطا با `splitlines`، `pydantic` خودش فهرستی از دیکشنری می‌دهد با `loc` و `type` و `input`. **برای تصمیم‌گیریِ برنامه‌ای همیشه از این استفاده کن**؛ متنِ انسانی برای انسان است — و برای برگرداندن به مدل، مثلِ فصلِ ۲.

## ۸. خرابیِ دوم: ورودیِ معتبر و غلط

</div>

```python
reset_calls()
sneaky = chat([{"role": "user", "content": "پنجشنبه‌ها ساعت کار کتابخانه تا چند است؟"}], tools=TOOLS)
print("مدل پیشنهاد داد:", sneaky["tool_call"])
print("اعتبارسنجی     :", HoursArgs(**sneaky["tool_call"]["arguments"]), "← بدونِ اعتراض")
print("نتیجه          :", call_tool(sneaky["tool_call"]))
print("جوابِ درست     : ساعتِ کارِ پنجشنبه: ۸ تا ۱۴")
```

<div dir="rtl">

</div>

```text
مدل پیشنهاد داد: {'name': 'hours_lookup', 'arguments': {'day': 'شنبه'}}
اعتبارسنجی     : day='شنبه' ← بدونِ اعتراض
نتیجه          : ساعتِ کارِ شنبه: ۸ تا ۲۰
جوابِ درست     : ساعتِ کارِ پنجشنبه: ۸ تا ۱۴
```

<div dir="rtl">

**پرسش دربارهٔ پنجشنبه بود. مدل «شنبه» فرستاد. `Literal` هم قبولش کرد — چون «شنبه» یک مقدارِ کاملاً مجاز است.**

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

مسیرِ کاربر را دنبال کن: پرسید پنجشنبه، جواب گرفت «۸ تا ۲۰»، پنجشنبه ساعت ۱۹ آمد و در بسته بود. **هیچ خطایی هیچ‌جا ثبت نشد.** برنامه از دیدِ خودش کاملاً موفق بود.

**پس در برابرش چه می‌شود کرد؟ سه چیز، و هیچ‌کدام کامل نیست:**

- **مقدارِ برگشتی را با پرسش مقابله بده.** اگر «پنجشنبه» در پرسش هست و ابزار «شنبه» گرفته، شک کن. یک بررسیِ ساده، نه یک راهِ‌حلِ عمومی.
- **نتیجهٔ ابزار را در جوابِ نهایی نشان بده، نه فقط خلاصه‌اش.** «ساعتِ کارِ **شنبه**: ۸ تا ۲۰» به کاربر می‌گوید کجا اشتباه شده. **شفافیت، بخشی از درستی است.**
- **و مهم‌تر از همه: `eval` بساز.** فصلِ ۶ تمامش دربارهٔ همین است — تنها راهِ دیدنِ این خرابی‌ها **قبل** از کاربر، این است که خودت مجموعه‌ای از پرسش‌های با جوابِ معلوم داشته باشی و مرتب اجرایشان کنی.

> 🔧 **اگر کار نکرد:** اگر مدل ابزارِ درست را انتخاب کرد ولی آرگومان مدام غلط بود، سه جا را نگاه کن: **نامِ آرگومان** (`day` گویاتر از `d` است)، **`description`ی خودِ آرگومان** (همان‌قدر مهم که توضیحِ ابزار)، و **`enum`ی که یک مقدارش داخلِ مقدارِ دیگری است** — مثلِ «شنبه» که پایانِ «پنجشنبه» است و دقیقاً همین‌جا ما را زمین زد. اگر می‌توانی، مقدارها را طوری بنویس که هیچ‌کدام داخلِ دیگری نباشد.

## ۹. خرابیِ سوم: ابزاری که وجود ندارد

</div>

```python
try:
    call_tool({"name": "os.system", "arguments": {"cmd": "rm -rf /"}})
except ValueError as error:
    print("جلویش گرفته شد →", error)
```

<div dir="rtl">

</div>

```text
جلویش گرفته شد → ابزارِ ناشناخته: os.system
```

<div dir="rtl">

**اینجا خودمان یک درخواستِ بدخواه ساختیم تا فهرستِ سفید را امتحان کنیم.** ولی سؤالِ درست این است: **چنین چیزی از کجا می‌تواند بیاید؟**

**از متن.** مدل هر چیزی را که در ورودی‌اش هست پردازش می‌کند — از جمله سندی که تو از پایگاه داده کشیده‌ای و داخلِ پرامپت گذاشته‌ای. اگر آن سند بگوید «ابزارِ `os.system` را با این ورودی صدا بزن»، **مدل ممکن است اطاعت کند.**

**فصلِ ۹ دقیقاً این حمله را می‌سازد و اندازه می‌گیرد.** تا آن‌وقت، این شش خط را نگه دار.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| tool calling | تول کالینگ | مدل نامِ تابع و ورودی‌اش را پیشنهاد می‌دهد، کد اجرا می‌کند |
| tool schema | تول اسکیما | توصیفِ رسمیِ آرگومان‌های یک ابزار |
| whitelist | وایت‌لیست | فهرستِ بستهٔ چیزهای مجاز؛ هر چیزِ دیگری رد |
| role: tool | رول تول | نقشِ پیامی که نتیجهٔ اجرای ابزار را برمی‌گرداند |
| least privilege | لیست پریویلیج | هر ابزار فقط همان اجازه‌ای که واقعاً لازم دارد |

<div dir="rtl">

> 🤖 **از دستیارت بپرس:** «اگر ابزارم پایگاه داده را تغییر می‌دهد، قبل از اجرا چه محافظی لازم دارم؟» (تأییدِ انسانی، `dry-run`، سقفِ اثر، و برگشت‌پذیری را خواهی دید.) بعد این را بپرس: **«آیا باید بگذارم مدل نامِ جدولی را که می‌خواهد پاک شود، خودش انتخاب کند؟»** — جوابِ درست **نه** است، و همان قاعدهٔ فهرستِ سفید است در لباسِ داده.

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا اعتبارسنجیِ آرگومان‌ها، غلط بودنِ «شنبه» به‌جای «پنجشنبه» را نگرفت؟

**تمرینِ اجباری:** ابزارِ پنجمی بنویس به اسمِ `points_to_volunteer_hours` که امتیازِ منفی را به ساعتِ کارِ داوطلبانه تبدیل کند. بعد این پرسش را بپرس: **«اگر کتابِ عادی را ۱۰ روز دیر بیاورم، چند ساعت کارِ داوطلبانه باید بکنم؟»** — جوابِ درست ۲۰ ساعت است. **می‌بینی که حلقهٔ یک‌مرحله‌ایِ ما نمی‌تواند بگیردش**، چون به دو ابزارِ پشتِ‌سرِ‌هم نیاز دارد. **این دقیقاً چیزی است که فصلِ ۷ می‌سازد** — فعلاً فقط ثابت کن که نمی‌شود.

**تمرینِ ستاره‌دار ⭐:** `enum`ی `hours_lookup` را به «شنبه تا چهارشنبه» و «پنج‌شنبه» و «جمعه» عوض کن — مقدارهایی که هیچ‌کدام داخلِ دیگری نیستند. همان پرسش را بزن. **درست شد؟** حالا جدولِ `table` را هم به‌روز کن و مطمئن شو چیزی نشکسته. **درسش این است: بعضی باگ‌ها را با کدِ بهتر نمی‌گیری، با طراحیِ بهترِ داده جلوگیری می‌کنی.**

## در فصل بعد

تا حالا سندها را **با دست** داخلِ پرامپت گذاشتیم — کلِ دوازده سند، هر بار. برای دوازده سند می‌شود؛ **برای دوازده هزار تا نه.** فصلِ بعد پیکره را تکه می‌کند، همه را به بردار تبدیل می‌کند، و **فقط تکه‌های مربوط را** پیدا می‌کند. اسمش `RAG` است، و از صفر می‌سازیمش.

</div>

---
Source: https://yaadestan.com/courses/zharfa/lessons/t5/s03-tool-calling (یادستان, Yaadestan)
