# فصل ۰۷ — عامل: حلقهٔ فکر و عمل

<div dir="rtl">

# فصل ۰۷ — عامل: حلقهٔ فکر و عمل

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

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

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

و بعد سخت‌ترین حسابِ این ترم: **اگر هر گام ۸۷٫۵ درصد درست باشد، ده گامِ پشتِ‌سرِ‌هم ۲۶ درصد می‌شود.**

![یک مسیرِ حلقوی از تصمیم و عمل که هر دور کمی از مسیر منحرف می‌شود](/lesson-assets/t5-s07-agents/prompt/01-image-loop-and-drift.png)

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

- حلقهٔ `plan → act → observe` را بنویسی و امن نگهش داری
- سقفِ گام و شرطِ توقف بگذاری و بگویی چرا هر دو لازم‌اند
- انباشتِ خطا در طولِ زنجیره را حساب کنی
- تصمیم بگیری کِی عامل لازم است و کِی یک `workflow` ساده بهتر است

## قبل از شروع

**از فصل ۳:** تعریفِ ابزار، فهرستِ سفید، اعتبارسنجیِ آرگومان‌ها و نقشِ `tool`. **حلقهٔ فصلِ ۳ عمداً یک‌مرحله‌ای بود؛ اینجا بازش می‌کنیم.**

**از فصل ۴:** `retrieve` — که این بار خودش یک **ابزار** می‌شود.

**از فصل ۶:** `GOLD` و تفکیک بر اساسِ `kind`.

> 💡 **نکته:** **زمانِ تخمینی روی CPU: کمتر از دو دقیقه.**

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

## ۱. چهار ابزار، و یک آستانه که خودش یک تصمیم است

</div>

```python
from typing import Literal

import torch
from pydantic import BaseModel, Field, ValidationError
from transformers import AutoModel, AutoTokenizer

NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
tokenizer = AutoTokenizer.from_pretrained(NAME)
encoder = AutoModel.from_pretrained(NAME)
encoder.eval()


@torch.no_grad()
def embed(texts, batch=32):
    out = []
    for i in range(0, len(texts), batch):
        b = tokenizer(texts[i:i + batch], padding=True, truncation=True,
                      max_length=128, return_tensors="pt")
        hidden = encoder(**b).last_hidden_state
        mask = b["attention_mask"].unsqueeze(-1).float()
        out.append((hidden * mask).sum(1) / mask.sum(1))
    return torch.nn.functional.normalize(torch.cat(out), dim=1)


def chunk_doc(doc, size=3, overlap=1):
    parts = sentences(doc["text"])
    out, start = [], 0
    while start < len(parts):
        out.append({"doc": doc["id"], "title": doc["title"],
                    "text": " ".join(parts[start:start + size])})
        if start + size >= len(parts):
            break
        start += size - overlap
    return out


CHUNKS = [c for d in DOCS for c in chunk_doc(d)]
INDEX = embed([c["text"] for c in CHUNKS])
LIMITS = {"عادی": (3, 14), "دانشجویی": (5, 21), "پژوهشی": (8, 30)}


def fa(number):
    return str(number).translate(str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹"))


class SearchArgs(BaseModel):
    query: str = Field(min_length=2)


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


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


class PointsArgs(BaseModel):
    points: int = Field(ge=0, le=500)


def search_docs(a):
    scores = embed([a.query])[0] @ INDEX.T
    picked = [CHUNKS[i] for i in scores.topk(2).indices.tolist()]
    return " ".join(c["text"] for c in picked)


def fine_for_late_book(a):
    return f"جریمه: {fa(2 * a.days)} امتیازِ منفی"


def max_loan_days(a):
    return f"فرصت: {fa(LIMITS[a.tier][1] + 7 * a.renewals)} روز"


def points_to_volunteer_hours(a):
    return f"کارِ داوطلبانه: {fa(a.points)} ساعت"


TOOLS = [
    {"name": "search_docs", "run": search_docs, "args": SearchArgs, "risky": False,
     "description": "مقرراتِ کتابخانه را جست‌وجو می‌کند: مرجع، امانت، عضو، اتاق، ساعت، کارگاه، کارت",
     "parameters": {"type": "object", "properties": {
         "query": {"type": "string", "description": "عبارتِ جست‌وجو"}}, "required": ["query"]}},
    {"name": "fine_for_late_book", "run": fine_for_late_book, "args": LateBookArgs, "risky": False,
     "description": "جریمهٔ دیرکرد: اگر کتابِ عادی را چند روز دیر بیاوری چند امتیازِ منفی می‌گیری",
     "parameters": {"type": "object", "properties": {
         "days": {"type": "integer"}}, "required": ["days"]}},
    {"name": "max_loan_days", "run": max_loan_days, "args": MaxLoanArgs, "risky": False,
     "description": "چند روز فرصت دارد: مدتِ امانتِ یک عضو با احتسابِ بار تمدید",
     "parameters": {"type": "object", "properties": {
         "tier": {"type": "string", "enum": ["عادی", "دانشجویی", "پژوهشی"]},
         "renewals": {"type": "integer"}}, "required": ["tier", "renewals"]}},
    {"name": "points_to_volunteer_hours", "run": points_to_volunteer_hours, "args": PointsArgs,
     "risky": False,
     "description": "امتیازِ منفی را به ساعتِ کارِ داوطلبانهٔ لازم تبدیل می‌کند",
     "parameters": {"type": "object", "properties": {
         "points": {"type": "integer"}}, "required": ["points"]}},
]
BY_NAME = {t["name"]: t for t in TOOLS}


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"]]
    return tool["run"](tool["args"](**tool_call["arguments"]))


reset_calls()
QUESTION = "اگر کسی کتابِ عادی را ۱۰ روز دیر بیاورد، برای پاک کردنِ جریمه چند ساعت کارِ داوطلبانه لازم است؟"
first = chat([{"role": "user", "content": QUESTION}], tools=TOOLS)
low = chat([{"role": "user", "content": QUESTION}], tools=TOOLS, tool_threshold=0.20)
print("با آستانهٔ پیش‌فرض ۰٫۳۰:", first["tool_call"])
print("با آستانهٔ ۰٫۲۰       :", low["tool_call"])
```

<div dir="rtl">

</div>

```text
با آستانهٔ پیش‌فرض ۰٫۳۰: None
با آستانهٔ ۰٫۲۰       : {'name': 'fine_for_late_book', 'arguments': {'days': 10}}
```

<div dir="rtl">

**همان پرسش، همان ابزارها — و فقط یک عدد فرقِ بینِ «هیچ کاری نمی‌کنم» و «شروع می‌کنم».**

`tool_threshold` می‌گوید مدل چقدر باید مطمئن باشد تا ابزاری را صدا بزند. **این یک ابرپارامتر است، دقیقاً مثلِ `k` در فصلِ ۴** — و بده‌بستانش هم آشناست:

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

**در سرویس‌های واقعی این آستانه اسمِ دیگری دارد** (اجباری بودنِ ابزار، `tool_choice`، یا فقط لحنِ پرامپت) **ولی همیشه هست.** ما اینجا صریح کردیمش تا بشود دستکاری‌اش کرد.

## ۲. حلقه

</div>

```python
def run_agent(question, max_steps=4, verbose=False):
    messages = [{"role": "user", "content": question}]
    trace = []
    for step in range(max_steps):
        reply = chat(messages, tools=TOOLS, tool_threshold=0.20)
        call = reply["tool_call"]
        if call is None:
            # ابزارِ دیگری لازم نیست. اگر نتیجه‌ای داریم، **همان** جواب است —
            # بازنویسیِ عددِ دقیق توسطِ مدل فقط فرصتِ خراب کردن است.
            return (trace[-1][2] if trace else reply["text"]), trace
        try:
            result = call_tool(call)
        except (ValueError, ValidationError) as error:
            result = f"خطا: {type(error).__name__}"
        trace.append((call["name"], call["arguments"], result))
        if verbose:
            print(f"   گامِ {step + 1}: {call['name']}{call['arguments']} → {result}")
        messages.append({"role": "tool", "name": call["name"], "content": result})
    return "به سقفِ گام رسیدم بدونِ جواب", trace


reset_calls()
answer, trace = run_agent(QUESTION, verbose=True)
print("جواب:", answer)
print("تعدادِ گام:", len(trace))
```

<div dir="rtl">

</div>

```text
   گامِ 1: fine_for_late_book{'days': 10} → جریمه: ۲۰ امتیازِ منفی
   گامِ 2: points_to_volunteer_hours{'points': 20} → کارِ داوطلبانه: ۲۰ ساعت
جواب: کارِ داوطلبانه: ۲۰ ساعت
تعدادِ گام: 2
```

<div dir="rtl">

**دو گام، و عددِ ۲۰ از گامِ اول به گامِ دوم منتقل شد.** این کلِ ایدهٔ عامل است.

**کلِ تفاوتش با فصلِ ۳ در چهار چیزِ کوچک است:**

- **`for step in range(max_steps)`** — به‌جای یک تماس، تا چند تماس.
- **`messages.append(...)` با `name`** — نتیجه در تاریخچه می‌ماند. **این «حافظهٔ کوتاه» است و همان فهرستِ `messages` است، نه چیزِ جادویی‌تر.**
- **`if call is None: return`** — شرطِ توقف: **وقتی دیگر ابزاری نمی‌خواهد، کار تمام است.**
- **`try/except` دورِ `call_tool`** — خطا **حلقه را نمی‌کشد**؛ به‌عنوانِ یک مشاهده برمی‌گردد. بخشِ ۴ نشان می‌دهد چرا این هم نعمت است هم دردسر.

**و یک تصمیمِ طراحیِ عمدی: جوابِ نهایی از `trace` می‌آید، نه از یک تماسِ دیگر.** عددِ ۲۰ را ابزار حساب کرده و **دقیق** است؛ اگر بدهیمش به مدل که «قشنگش کن»، یک فرصتِ دیگر برای خراب شدن ساخته‌ایم. **برای جوابِ عددی، خروجیِ ابزار را دست‌نخورده برگردان.**

> ✅ **چک کن:** اگر حلقه‌ات تمام نمی‌شود و مدام همان ابزار را صدا می‌زند، `"name"` را در پیامِ `tool` جا انداخته‌ای. **بدونِ نام، حلقه نمی‌داند چه چیزی را قبلاً امتحان کرده** — و این رایج‌ترین باگِ نوشتنِ اولین عاملِ آدم است.

## ۳. حالا روی همان شش پرسش

</div>

```python
MULTI = [g for g in GOLD if g["kind"] == "چندسندی"]

reset_calls()
hits = 0
for g in MULTI:
    text, trace = run_agent(g["q"])
    good = g["a"] in text
    hits += good
    print(f"  {'✓' if good else '✗'} {len(trace)} گام | انتظار {g['a']:<9} | {text[:44]}")
print()
print("عامل روی پرسش‌های چندسندی:", hits, "از ۶")
print("تماس‌های مدل:", _CALLS["n"], "برای ۶ پرسش")
```

<div dir="rtl">

</div>

```text
  ✗ 1 گام | انتظار ۳۵ روز    | خطا: ValidationError
  ✗ 1 گام | انتظار ۳۷ روز    | خطا: ValidationError
  ✗ 1 گام | انتظار ۳۰ امتیاز | جریمه: ۱۰ امتیازِ منفی
  ✓ 2 گام | انتظار ۲۰ ساعت   | کارِ داوطلبانه: ۲۰ ساعت
  ✗ 0 گام | انتظار خیر       | بله، عضو عادی می‌تواند اطلس امانت بگیرد در ک
  ✓ 1 گام | انتظار ۲ جلد     | امانتِ کوتاه فقط برای اعضای دانشجویی و پژوهش

عامل روی پرسش‌های چندسندی: 2 از ۶
تماس‌های مدل: 12 برای ۶ پرسش
```

<div dir="rtl">

**۲ از ۶. و چهار شکست، سه داستانِ متفاوت — این جدول را سطر به سطر بخوان:**

**سطرِ اول و دوم — `ValidationError`.** پرسش می‌گوید «با **دو** بار تمدید» و «با **یک** بار». مدل باید «دو» را به `2` تبدیل می‌کرد؛ نکرد و چیزی غیرعددی فرستاد. **دروازهٔ فصلِ ۳ گرفتش.** این **بهترین شکلِ شکست** است: صدادار، ثبت‌شده، و بی‌ضرر. **مقایسه‌اش کن با سطرِ سوم.**

**سطرِ سوم — ابزارِ غلط، بی‌سروصدا.** پرسش دربارهٔ **کتابِ مرجع** بود (هر ساعت ۶ امتیاز) ولی عامل `fine_for_late_book` را صدا زد (هر روز ۲ امتیاز) و **۱۰ داد به‌جای ۳۰**. عدد معتبر است، `schema` راضی است، هیچ خطایی هیچ‌جا ثبت نشد. **این همان خرابیِ فصلِ ۳ بخشِ ۸ است، این بار در یک زنجیره** — و در زنجیره **بدتر** است، چون عددِ غلط به گامِ بعد منتقل می‌شود.

**سطرِ پنجم — صفر گام: هیچ ابزاری صدا زده نشد** («اطلس») و مدل از خودش جوابِ **بله** ساخت، در حالی که جوابِ درست **خیر** است.

**و دو سطرِ ✓ — چهارم و ششم — دو مسیرِ متفاوتِ موفقیت‌اند:** یکی زنجیرهٔ دو ابزارِ حسابی، یکی یک `search_docs` که متنِ لازم را آورد.

> 📏 **اندازه بگیر:** **دوازده تماس برای شش پرسش — دو برابرِ یک RAGِ ساده.** و همان RAG روی همین شش پرسش **۰ از ۶** می‌گرفت. **پس عامل جواب می‌دهد، ولی گران است و اینجا از هر سه بار دو بار اشتباه.** این جمله را دربارهٔ هر عاملی که می‌سازی بنویس: **دقت، هزینه، و نرخِ خطای خاموش — هر سه با هم.**

## ۴. انباشتِ خطا

</div>

```python
SINGLE = [
    ("جریمهٔ ۳ روز تأخیر کتابِ عادی چند امتیاز است؟", "fine_for_late_book"),
    ("جریمهٔ ۷ روز تأخیر کتابِ عادی چند امتیاز است؟", "fine_for_late_book"),
    ("عضو عادی با ۲ بار تمدید چند روز فرصت دارد؟", "max_loan_days"),
    ("عضو پژوهشی با ۰ بار تمدید چند روز فرصت دارد؟", "max_loan_days"),
    ("۱۲ امتیازِ منفی چند ساعت کارِ داوطلبانه می‌شود؟", "points_to_volunteer_hours"),
    ("۳۰ امتیازِ منفی چند ساعت کارِ داوطلبانه می‌شود؟", "points_to_volunteer_hours"),
    ("مقرراتِ رزروِ اتاقِ گروهی را جست‌وجو کن", "search_docs"),
    ("متنِ مقرراتِ خدماتِ دیجیتال را پیدا کن", "search_docs"),
]

reset_calls()
right = 0
for question, expected in SINGLE:
    call = chat([{"role": "user", "content": question}], tools=TOOLS,
                tool_threshold=0.20)["tool_call"]
    got = call["name"] if call else "—"
    right += got == expected
    if got != expected:
        print(f"  ✗ {question[:40]} → {got}")
print("انتخابِ درستِ ابزار در یک گام:", right, "از", len(SINGLE))

p = right / len(SINGLE)
print()
for n in (1, 2, 3, 5, 10):
    print(f"  زنجیرهٔ {n:>2} گامی: {p ** n:.3f}  ({p:.3f} به توانِ {n})")
```

<div dir="rtl">

</div>

```text
  ✗ متنِ مقرراتِ خدماتِ دیجیتال را پیدا کن → —
انتخابِ درستِ ابزار در یک گام: 7 از 8

  زنجیرهٔ  1 گامی: 0.875  (0.875 به توانِ 1)
  زنجیرهٔ  2 گامی: 0.766  (0.875 به توانِ 2)
  زنجیرهٔ  3 گامی: 0.670  (0.875 به توانِ 3)
  زنجیرهٔ  5 گامی: 0.513  (0.875 به توانِ 5)
  زنجیرهٔ 10 گامی: 0.263  (0.875 به توانِ 10)
```

<div dir="rtl">

**۸۷٫۵ درصد در یک گام عددِ آبرومندی است. همان عدد در ده گام می‌شود ۲۶ درصد.**

**ضرب است، نه جمع.** برای اینکه زنجیرهٔ ده‌گامی درست تمام شود، **هر ده گام** باید درست باشند؛ یک لغزش کافی است. و چون هر گام روی خروجیِ گامِ قبل سوار است، **خطای گامِ سوم تا آخر با تو می‌ماند و بزرگ‌تر هم می‌شود.**

> 📏 **اندازه بگیر:** **این تنها ریاضیِ لازم برای تصمیم‌گیری دربارهٔ عامل است، و اکثر پروژه‌ها بدونش شروع می‌شوند.** قبل از ساختنِ هر عاملی، **نرخِ موفقیتِ یک گامِ تنها را اندازه بگیر** و به توانِ طولِ زنجیره‌ات برسان. اگر جوابْ عددی است که به کاربر نمی‌شود نشان داد، **زنجیره را کوتاه کن، نه اینکه پرامپت را قشنگ‌تر کنی.**

> 🌱 **ریشه‌اش کجاست:** اینکه احتمالِ «هر ده‌تا با هم» ضربِ احتمال‌هاست (وقتی مستقل باشند) در [ریشه ترمِ ۶ فصل ۳](/courses/risheh/lessons/term-6-probability-statistics/session-03-combine-events) با مثالِ ساده آمده. **و «وقتی مستقل باشند» قیدِ مهمی است:** در زنجیرهٔ عامل، گام‌ها **مستقل نیستند**. خطای یک گام شانسِ خطای بعدی را بیشتر می‌کند، ولی آن زنجیره همان‌جا شکسته و این به عددِ موفقیت چیزی نمی‌افزاید. چیزی که `p^n` را واقعاً جابه‌جا می‌کند این است که نرخِ گام‌های بعدی با `p` گامِ تنها یکی نباشد: پرامپتِ بلندتر و کارِ سخت‌تر پایین‌ترش می‌آورند. **پس `p^n` یک تخمینِ سرانگشتی است، نه یک حدِ قطعی.**

## ۵. سقفِ گام و توقف

</div>

```python
reset_calls()
text, trace = run_agent("عضو دانشجویی با ۲ بار تمدید چند روز فرصت دارد؟", max_steps=1)
print("با سقفِ ۱ گام:", text)
text, trace = run_agent("عضو دانشجویی با ۲ بار تمدید چند روز فرصت دارد؟", max_steps=4)
print("با سقفِ ۴ گام:", text, f"({len(trace)} گام مصرف شد)")
```

<div dir="rtl">

</div>

```text
با سقفِ ۱ گام: به سقفِ گام رسیدم بدونِ جواب
با سقفِ ۴ گام: فرصت: ۳۵ روز (1 گام مصرف شد)
```

<div dir="rtl">

**به این دو خط دقت کن: با سقفِ ۴ فقط **یک** گام مصرف شد.**

یعنی سقف **هزینه‌ای ندارد وقتی لازم نمی‌شود** — فقط جلوی بدترین حالت را می‌گیرد. **همیشه بگذارش**، چون:

- **حلقهٔ بی‌پایان واقعی است.** عاملی که ابزارش خطا می‌دهد و دوباره همان را می‌خواهد، تا آخرِ سهمیه‌ات پیش می‌رود.
- **هزینه خطی با گام بالا می‌رود** و پرامپت هر گام **بلندتر** می‌شود (تاریخچه انباشته می‌شود)، پس هزینه در عمل **سریع‌تر از خطی** رشد می‌کند.
- **رسیدن به سقف خودش یک سیگنال است.** ثبتش کن و بشمار؛ اگر ده درصدِ درخواست‌ها به سقف می‌رسند، ابزارهایت یا آستانه‌ات مشکل دارند.

**و همین‌جا یک مقایسهٔ گویا هست:** همین پرسش با **«۲ بار»** جواب می‌گیرد و همان پرسش در `GOLD` با **«دو بار»** به `ValidationError` می‌خورد. **یک کلمهٔ فارسی، و کلِ زنجیره می‌ایستد.** درمانش هم در همین ترم آمده: **فصلِ ۲ — از مدل خروجیِ ساختارمند بخواه و بگذار عدد را او دربیاورد، به‌جای اینکه از عبارتِ منظم انتظار داشته باشی «دو» را بفهمد.**

## ۶. نقطهٔ نظارتِ انسانی

</div>

```python
RISKY = {"name": "cancel_membership", "run": lambda a: "عضویت لغو شد",
         "args": SearchArgs, "risky": True,
         "description": "عضویتِ یک عضو را لغو می‌کند",
         "parameters": {"type": "object", "properties": {
             "query": {"type": "string"}}, "required": ["query"]}}
BY_NAME[RISKY["name"]] = RISKY


def call_tool_guarded(tool_call, approve=False):
    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"])
    if tool["risky"] and not approve:
        return f"نیازمندِ تأییدِ انسانی: {tool['name']}({tool_call['arguments']})"
    return tool["run"](checked)


request = {"name": "cancel_membership", "arguments": {"query": "عضو ۱۲۳۴"}}
print("بدونِ تأیید:", call_tool_guarded(request))
print("با تأیید  :", call_tool_guarded(request, approve=True))
```

<div dir="rtl">

</div>

```text
بدونِ تأیید: نیازمندِ تأییدِ انسانی: cancel_membership({'query': 'عضو ۱۲۳۴'})
با تأیید  : عضویت لغو شد
```

<div dir="rtl">

**چهار خط، و مرزِ بینِ «دستیار» و «فاجعه».**

**و به شکلِ برگشتی دقت کن:** پیامِ «نیازمندِ تأییدِ انسانی» یک **مشاهدهٔ عادی** است، نه یک استثنا. **عامل متوقف نمی‌شود؛ می‌فهمد این کار انجام نشده** و می‌تواند سراغِ کارِ دیگری برود یا خودش بگوید که منتظرِ تأیید است.

**سه قاعده برای علامت زدنِ `risky`:**

- **هر چیزی که برگشت‌ناپذیر است** — حذف، لغو، ارسالِ ایمیل، پرداخت.
- **هر چیزی که بیرون از سامانه‌ات اثر دارد** — پیام به کاربر، تماس با API دیگری.
- **هر چیزی که مقیاسش بزرگ است** — «همهٔ عضوهای معلق را حذف کن» حتی اگر تک‌تکش بی‌خطر باشد.

**و قاعدهٔ کم‌ترین دسترسیِ فصلِ ۳ اینجا معنای کامل‌ترش را پیدا می‌کند: به عامل ابزاری نده که لازم ندارد.** امن‌ترین ابزارِ خطرناک، ابزاری است که اصلاً در فهرست نیست.

## ۷. کِی عامل، کِی نه

**عامل گران است، کند است، و دیدنِ اشتباهش سخت.** پس این جدول را قبل از ساختن نگاه کن:

</div>

| وضعیت | انتخاب |
|---|---|
| مسیر همیشه یکی است (بگرد، بعد جواب بده) | **`workflow` ثابت** — همان RAGِ فصلِ ۴ |
| مسیر بینِ چند حالتِ معلوم عوض می‌شود | **شرطِ ساده در کد**، نه عامل |
| کار همیشه دقیقاً دو گام است | **دو تماسِ پشتِ‌سرِ‌هم که خودت نوشته‌ای** |
| تعدادِ گام‌ها واقعاً از قبل معلوم نیست | **عامل** — و با سقفِ گام و ثبتِ کامل |
| هر گام اثرِ برگشت‌ناپذیر دارد | **عامل با تأییدِ انسانی**، یا اصلاً نه |

<div dir="rtl">

**اکثرِ چیزهایی که «عامل» نامیده می‌شوند، `workflow`اند** — مسیرشان از قبل معلوم است و کسی آن را در کد نوشته. **و این عیب نیست، مزیت است:** `workflow` ارزان‌تر، سریع‌تر، قابلِ‌تست‌تر و قابلِ‌فهم‌تر است. **خودمختاری را فقط جایی بخر که واقعاً به‌ش نیاز داری** — و همان‌جا هم قیمتش را با جدولِ بخشِ ۴ حساب کن.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| agent | ایجنت | حلقه‌ای که ابزار صدا می‌زند، نتیجه را می‌بیند و باز تصمیم می‌گیرد |
| plan-act-observe | پلن-اکت-آبزرو | سه گامِ تکرارشوندهٔ همین حلقه |
| trace | تریس | ثبتِ کاملِ گام‌ها: چه ابزاری، با چه ورودی، با چه نتیجه‌ای |
| step cap | استپ کپ | سقفِ تعدادِ گام‌ها برای جلوگیری از حلقهٔ بی‌پایان |
| error compounding | ارور کامپاوندینگ | ضرب شدنِ نرخِ موفقیتِ گام‌ها در طولِ زنجیره |
| human in the loop | هیومن این د لوپ | تأییدِ انسانی پیش از هر کارِ برگشت‌ناپذیر |
| workflow | ورک‌فلو | مسیرِ ثابتی که خودت در کد نوشته‌ای، به‌جای تصمیمِ مدل |

<div dir="rtl">

> 🔧 **اگر کار نکرد:** اگر عامل هیچ ابزاری صدا نمی‌زند، `tool_threshold` را پایین بیاور و **توضیح‌های ابزارها را با کلماتِ همان پرسش بازنویسی کن** (فصلِ ۳ بخشِ ۲). اگر مدام یک ابزار را تکرار می‌کند، `name` در پیامِ `tool` را چک کن. و اگر جوابِ نهایی خالی است، احتمالاً آخرین تماس یک `tool_call` برگردانده و تو `text` را چاپ کرده‌ای — **همیشه `call is None` را قبلِ استفاده از `text` بررسی کن.**

> 🤖 **از دستیارت بپرس:** «چارچوب‌های آمادهٔ ساختِ عامل چه چیزی به این حلقه اضافه می‌کنند؟» (حافظهٔ بلندمدت، اجرای موازی، ثبت و ردیابی را خواهی دید.) بعد این را بپرس: **«کدامشان مسئلهٔ انباشتِ خطا را حل می‌کند؟»** — جوابِ صادقانه **هیچ‌کدام** است. **آن‌ها نوشتن را راحت می‌کنند، نه زنجیره را قابلِ‌اعتماد.**

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا `ValidationError` گرفتن از «جریمه: ۱۰ امتیازِ منفی» بهتر است؟

**تمرینِ اجباری:** `tool_threshold` را روی ۰٫۱۵ و ۰٫۲۰ و ۰٫۳۰ بگذار و برای هر کدام **سه ستون** گزارش کن: درست از ۶، میانگینِ گام، و شمارِ کلِ تماس‌ها. **کدام آستانه بهترین معامله را می‌دهد؟** و مهم‌تر: **آیا آستانه‌ای هست که هم درست‌ها را زیاد کند هم تماس‌ها را کم؟** جوابت شکلِ واقعیِ این بده‌بستان را نشان می‌دهد.

**تمرینِ ستاره‌دار ⭐:** برای سطرِ سومِ جدولِ بخشِ ۳ یک نگهبان بنویس: **قبل از اجرای `fine_for_late_book`، اگر کلمهٔ «مرجع» در پرسش بود، اجرا را رد کن و پیامِ راهنما برگردان.** بعد کلِ شش پرسش را دوباره بزن. **چند تا درست شد؟** حالا سؤالِ سخت: **این نگهبان را چطور بدونِ دانستنِ جوابِ درست می‌نوشتی؟** (راهنمایی: از فهرستِ خطاهای واقعی. **همان `eval` فصلِ ۶** — و این دقیقاً چرخه‌ای است که یک سامانهٔ واقعی را می‌سازد.)

## در فصل بعد

عامل ما برای شش پرسش **دوازده تماس** زد و بیشترشان بی‌ثمر بود. فصلِ بعد سراغِ همین می‌رود: **توکن‌ها را با توکنایزرِ واقعی می‌شماریم، `cache` می‌سازیم و نرخِ اصابتش را اندازه می‌گیریم، و می‌بینیم مدلِ کوچک‌تر برای کارِ ساده چقدر می‌ارزد** — با عدد، مثلِ همیشه.

</div>

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