حلقه‌ی ایجنت، طراحی ابزار و مدیریت کانتکست

از این جلسه به بعد از جای کاربر بیرون می‌آییم و جای طراح ایجنت می‌نشینیم. سه جزء یک ایجنت کدنویس یک پنجره‌ی کانتکست مشترک دارند و باید با هم طراحی شوند:

1. مدل + حلقه: ایجنت یعنی یک مدل در یک حلقه
2. ابزارها و محافظ‌ها: جستجو، خواندن، ویرایش، اجرا، پشت مجوز و sandbox
3. حالت: آنچه الان در پنجره است و آنچه بین قدم‌ها می‌ماند

حلقه‌ی ReAct#

ReAct (Yao و همکاران، ۲۰۲۲) سه فاز را تکرار می‌کند:

• فکر (Thought): چه می‌دانم، چه کم دارم، قدم بعد چیست؟
• عمل (Action): یک فراخوانی ساخت‌یافته که محیط بتواند اجرا کند
• مشاهده (Observation): محیط واقعیت‌ها را برمی‌گرداند

چرا هر دو لازم‌اند؟

• فقط استدلال: هیچ چیز استدلال را بررسی نمی‌کند، پس خطاهای کوچک روی هم جمع می‌شوند و به توهم با اعتمادبه‌نفس می‌رسند.
• فقط عمل: فراخوانی‌ها برنامه ندارند و مدل خودش را تکرار می‌کند.
• ReAct: فکر عمل را هدایت می‌کند و مشاهده فکر را اصلاح می‌کند.

حلقه در کد#

کل هسته‌ی یک ایجنت در چند خط جا می‌شود. تابع llm را با فراخوانی هر ارائه‌دهنده‌ای که tool calling دارد جایگزین کنید:

import json

MAX_STEPS = 30

def run_agent(task: str, tools: dict, llm) -> str:
    messages = [
        {"role": "system", "content": "Solve the task using the tools."},
        {"role": "user", "content": task},
    ]
    for step in range(MAX_STEPS):
        reply = llm(messages, tools=[t.schema for t in tools.values()])
        messages.append(reply)
        if not reply.get("tool_calls"):
            return reply["content"]               # پاسخ نهایی

        for call in reply["tool_calls"]:
            tool = tools.get(call["name"])
            try:
                if tool is None:
                    raise ValueError(f"unknown tool {call['name']!r}; available: {list(tools)}")
                args = tool.validate(json.loads(call["arguments"]))   # اعتبارسنجی پیش از اجرا
                result = tool.run(**args)
            except Exception as e:                                    # خطا هم مشاهده است
                result = f"ERROR: {e}"
            messages.append({"role": "tool", "tool_call_id": call["id"],
                             "content": str(result)[:10_000]})        # خروجی محدود

    raise RuntimeError("step budget exhausted")

همین چند خط مسئولیت‌های طراح هارنس را نشان می‌دهد: ساختن کانتکست، اعتبارسنجی درخواست، بررسی مجوز، اجرای ابزار، پردازش نتیجه، مدیریت کانتکست و نوشتن تعریف ابزارها. باقی این جلسه درباره‌ی دو تصمیم مهم است: چه ابزاری بدهیم و چه چیزی در کانتکست بماند.

ابزار جستجو: ایجنت کد مربوط را چطور پیدا کند؟#

قاعده‌ی عملی: با grep شروع کنید. هیچ چیزی برای ساختن یا همگام کردن ندارد و همیشه وضعیت واقعی مخزن را می‌بیند. وقتی نام‌ها جواب ندادند، سراغ ایندکس یا LSP بروید. اگر stack trace یا تست شکسته دارید، دقیق‌ترین سیگنال همان است و اغلب اصلاً جستجو لازم نیست.

چهار مثال از اسلایدها، یکی برای هر روش:

• grep و glob، «timeout لاگین را درست کن»: grep در ۱۲ فایل ۳۷ نتیجه می‌دهد. glob دامنه را به auth/retry.ts محدود می‌کند. ایجنت فایل را می‌خواند و RETRY_MS را از ۵۰۰ تغییر می‌دهد.
• ایندکس معنایی، «کجا rate-limit می‌کنیم؟»: با اولین جستجو throttle.ts پیدا می‌شود، با اینکه کلمه‌ی rate-limit در آن نیست. ایندکس معنایی می‌تواند بر اساس embedding تکه‌های کد باشد، یا یک «نقشه‌ی مخزن» از فایل‌ها، کلاس‌ها و امضای توابع (روش Aider).
• سیگنال بیرونی، «crash در صفحه‌ی پرداخت»: stack trace به cart.ts:88 اشاره می‌کند. فریم‌ها به گرد کردن در applyTax داخل tax.ts می‌رسند. اصلاح و اجرای دوباره‌ی تست، بدون هیچ جستجویی.
• LSP، «تغییر نام charge() به capture()»: ۴۲ ارجاع در ۷ فایل پیدا می‌شود و همه، از جمله importهای با نام مستعار، تغییر می‌کنند و بعد type-check اجرا می‌شود. grep importهای مستعار و overloadها را فقط می‌تواند حدس بزند.

ابزار ویرایش: ایجنت کد را چطور تغییر دهد؟#

بیشتر ایجنت‌های امروز از جستجو و جایگزینی استفاده می‌کنند، با یک قید مهم: رشته‌ی قدیمی باید دقیقاً یک بار در فایل باشد. اگر صفر یا چند بار پیدا شود، ابزار خطا می‌دهد و مدل باید لنگر دقیق‌تری بدهد. هر هارنسی هم ترفندهای خودش را دارد. یکی بعد از چند تلاش سراغ تطبیق فازی می‌رود. دیگری خط‌ها را با هش برچسب می‌زند. سومی ویرایش را فقط وقتی قبول می‌کند که فایل از آخرین خواندن عوض نشده باشد (compare-and-swap).

مثال هر روش در اسلایدها:

روی دو محور هزینه‌ی توکن و استحکام (آیا ویرایش همان جایی می‌نشیند که باید؟)، هیچ روشی بر همه برتری ندارد.

ابزار اجرا: در عمل یک شل#

شل قدرتمندترین و خطرناک‌ترین ابزار است:

• ترکیب: یک فراخوانی می‌تواند زنجیر، فیلتر، حلقه و تلاش مجدد کند
• دسترسی: فایل‌سیستم، شبکه، package managerها، هر برنامه‌ی نصب‌شده
• ماندگاری: فایل‌ها و پروسه‌ها بعد از فراخوانی می‌مانند
• شعاع انفجار: هر کاری شل بتواند، ایجنت هم می‌تواند

ملاحظات طراحی: سیگنال شکست قابل اقدام، خروجی کافی اما نه بیش از حد، مدیریت پروسه‌های طولانی و پس‌زمینه، بودجه (کی دست از تلاش بکشد و کنترل را برگرداند) و ایزوله‌سازی (کد کجا اجرا می‌شود و به چه دسترسی دارد).

پنج ابزار پرکاربرد دیگر#

• یادداشت و حافظه: یافته‌ها را در فایل بنویس تا برنامه از compaction جان سالم به در ببرد
• زیرایجنت: جستجو یک فهرست کوتاه برمی‌گرداند، نه ۴۰ فایل خوانده‌شده
• جستجو و خواندن وب: اول سورس نصب‌شده را بخوان، بعد وب را
• مرورگر و بازخورد دیداری: از صفحه‌ی رندرشده عکس بگیر و به مدل نشان بده
• پرسیدن از کاربر: یک سؤال ارزان بهتر از یک patch غلط با اعتمادبه‌نفس است

اصول طراحی ابزار#

1. ابزار کم و متعامد: ابزارهای هم‌پوشان مدل را مردد می‌کنند.
2. ابزار هدفمند: search_orders(customer_id) بهتر از run_sql خام است.
3. خروجی کم‌توکن: کوتاه کنید، صفحه‌بندی کنید، خلاصه کنید. طراحی ابزار همان طراحی کانتکست است.
4. خطایی که یاد می‌دهد: به جای «invalid argument»، راه اصلاح را بگویید.
5. idempotent به‌طور پیش‌فرض: تا جای ممکن تکرار امن باشد.

مقایسه‌ی دو پیام خطا:

بد:  Error: invalid argument
خوب: Error: old_str found 3 times in auth.py (lines 12, 40, 88).
     Include more surrounding lines so the match is unique.

آیا فقط شل کافی نیست؟#

نموداری در اسلایدهای درس، برگرفته از آزمایش‌های SWE-agent با GPT-4، نرخ حل مسئله را با ابزارهای مختلف مقایسه می‌کند: بدون ویرایشگر تخصصی ۱۰٫۳٪، فقط شل ۱۱٫۰٪، نمایش کامل فایل ۱۲٫۷٪، تاریخچه‌ی کامل تعامل ۱۵٫۰٪، و ابزارهای اختصاصی SWE-agent ۱۸٫۰٪. ابزار و نمای اختصاصی کمک می‌کنند، هرچند مدل‌های قوی‌تر امروز این فاصله را کمتر کرده‌اند. این را خودتان با ایجنتتان آزمایش کنید.

از مهندسی پرامپت تا مهندسی هارنس#

اسلاید یادآوری می‌کند که این اصطلاح‌ها را آورده تا بشناسید، نه اینکه تأییدشان کند.

تکنیک‌های پرامپت در یک نگاه#

مثال‌هایی که اسلایدها برای هر تکنیک آورده‌اند، کمک می‌کند مرز بینشان روشن شود:

اسلاید انتخاب تکنیک را در سه پله خلاصه می‌کند: ساده شروع کنید (zero-shot، few-shot، نقش)، استدلال اضافه کنید (chain-of-thought، tree-of-thought، self-consistency)، و سیستم را مهندسی کنید (زنجیره‌ی پرامپت، meta prompting). هر تکنیک هم یک «کی سراغ بعدی بروید» دارد: وقتی قاعده ضمنی است از zero-shot به few-shot، وقتی کار قدم دارد به chain-of-thought، وقتی چند مسیر هست به tree-of-thought، وقتی یک جواب درست هست به self-consistency، وقتی مراحل جداشدنی‌اند به زنجیره، و وقتی خود پرامپت را تنظیم می‌کنید به meta prompting. اگر بهبود متوقف شد، انتخابتان را بازبینی کنید.

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

نمونه‌ی اسلاید برای ترتیب بخش‌ها: اول دستور، بعد جداکننده، بعد داده.

### Instruction ###
Translate the text below to Spanish:
Text: "hello!"

خروجی مدل: ¡Hola!

کانتکست یک منبع محدود است#

Karpathy مهندسی کانتکست را این‌طور تعریف کرده: «پر کردن پنجره‌ی کانتکست با دقیقاً اطلاعات درست برای قدم بعدی». سه دلیل که کانتکست بیشتر لزوماً بهتر نیست:

• هزینه: هر قدم کل پنجره را دوباره می‌فرستد، پس هر نوبت دوباره پرداخت می‌شود.
• تأخیر: پرامپت بزرگ‌تر یعنی prefill و decode کندتر در هر نوبت.
• توجه: با پر شدن پنجره یادآوری ضعیف می‌شود.

پژوهش «Lost in the Middle» (Liu و همکاران) نشان داد وقتی جواب بین ۲۰ سند پنهان است، دقت در حالتی که جواب در سند اول است حدود ۷۶٪ است، وقتی در میانه است به حدود ۵۵ تا ۶۱٪ می‌رسد و در انتها کمی بهتر می‌شود. گزارش «Context Rot» از Chroma هم افت دقت با بلندتر شدن ورودی را نشان داد. هم مقدار و هم جای اطلاعات مهم است.

کالبدشکافی پنجره#

یک بودجه‌ی نمونه برای یک نوبت ایجنت:

پرامپت سیستمی        ~2K
تعریف ابزارها        ~6K
کانتکست بازیابی‌شده  ~25K
محیط پروژه          ~8K
تاریخچه‌ی پیام‌ها (کاربر، مدل، نتیجه‌ی ابزارها)   80K و بیشتر، و در حال رشد

چهار راهبرد مدیریت پنجره#

از پیشگیرانه و بی‌اتلاف تا پرهزینه و برگشت‌ناپذیر:

جزئیات هر راهبرد:

• پذیرش: بازیابی هدفمند (فیلد بخواه، نه سند)، شکل دادن خروجی ابزار، برش فقط وقتی شکل دادن ممکن نیست، و سپردن داده‌ی خام به زیرایجنت.
• برون‌سپاری: تعریف ابزار تدریجی یا با جستجو، برگرداندن دستگیره به جای خروجی بزرگ (مسیر فایل)، فهرست کارها روی دیسک، و یادداشت پایدار با یک ایندکس کوچک.
• تبدیل: نگه داشتن فقط آخرین وضعیت هر شیء، پنهان کردن نتایج ابزار قدیمی‌تر از N قدم، و پنجره‌ی لغزان که ابتدای گفتگو را حفظ می‌کند.
• فشرده‌سازی: جا برای خروجی بگذارید، پیشوند سیستمی را دست نزنید (وگرنه prefix cache از دست می‌رود)، و بعد از خلاصه‌سازی واقعیت‌های حیاتی را دوباره تزریق کنید.

پنج حالت خرابی کانتکست#

Drew Breunig این پنج حالت را نام‌گذاری کرده است:

وقتی خرابی را نام‌گذاری کنید، راه‌حل معمولاً واضح می‌شود.

ایجنت = مدل × هارنس#

توانایی مدل سقف را تعیین می‌کند و هارنس تعیین می‌کند چقدر از آن سقف محقق شود. پژوهشی که در اسلایدها آمده (Lewis، ۲۰۲۶) با همان مدل و فقط تغییر هارنس این نتایج را گرفت:

تغییرات هارنس ساده بودند: فشرده کردن خروجی‌های قدیمی ابزار، نگه داشتن مشاهده‌های اخیر، تشخیص تکرار و گیر کردن، و دخالت وقتی ایجنت گیر کرده بود. بعضی از چیزهایی که «ضعف مدل» به نظر می‌رسند، در واقع خرابی کانتکست یا حلقه‌ی کنترل‌اند.

فراتر از ReAct#

پرسش‌هایی برای فکر کردن#

• در حلقه‌ی کد بالا، خروجی ابزار به ۱۰ هزار کاراکتر بریده شد. چه نوع خطایی ممکن است از این برش پنهان بماند؟ چه طراحی بهتری پیشنهاد می‌کنید؟
• اگر ایجنت شما ۶۰ ابزار MCP دارد، کدام راهبرد مدیریت کانتکست بیشترین اثر را دارد؟

منابع#

• اسلاید جلسه: Agents design I: context management and tool design (4_agent_design_1.pdf)
• Yao و همکاران، ReAct: Synergizing Reasoning and Acting in Language Models
• OpenAI، A practical guide to building agents
• Lilian Weng، LLM Powered Autonomous Agents
• Liu و همکاران، Lost in the Middle
• Drew Breunig، How Contexts Fail and How to Fix Them
• Lewis، Same Model, Different Harness (arXiv:2608.26218)