ساختن یا آماده برداشتن

mini حدود ۲۳۰ خط است و لیلا تک‌تکِ خط‌هایش را می‌فهمد. بعد یکی از همکارهایش چند خط کد نشانش می‌دهد که بخشِ بزرگی از کارِ حلقه‌ی mini را انجام می‌دهد، آن هم از همان بسته‌ی anthropic. همکارِ دیگری کتابخانه‌ای به کار می‌برد که ویرایشِ فایل، اجازه‌ها، هوک‌ها و فشرده‌سازی را از قبل ساخته و آماده دارد. یعنی لیلا وقتش را برای ساختنِ mini هدر داده است؟

لیلا اگر برای این کار کتابخانه هست، چرا حلقه را خودمان نوشتیم؟

امید وقتی mini کارِ عجیبی می‌کند، کجا را نگاه می‌کنی؟

لیلا می‌دانم کجا را. نتیجه‌ی ابزاری که به جای اشتباهی رفته، اجازه‌ای که گفته نه، فشرده‌سازی‌ای که جزئیاتی را از دست داده. هر کدام از این بخش‌ها را خودم نوشته‌ام.

امید و با کتابخانه‌ی یک نفرِ دیگر؟

لیلا درونِ کتابخانه را... ولی باز هم می‌دانم دنبالِ چه جور چیزی بگردم، چون آن هم باید همین کارها را بکند: حلقه را بچرخاند، نتیجه‌ها را برگرداند، اجازه‌ها را بررسی کند، زمینه را مدیریت کند.

امید این همان چیزی است که ساختنِ mini به تو داد: حالا می‌توانی هر هارنسی را بخوانی. پس کِی هنوز خودت یکی می‌نویسی؟

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

امید و کِی آماده برمی‌داری؟

لیلا وقتی عاملی بزرگ و جدی است. یک نفرِ دیگر آن صد موردِ مرزی را که من هنوز ندیده‌ام قبلاً پیدا کرده است.

کدِ آماده برای عامل

فریم‌ورکِ عامل (agent framework) کدی آماده است که حلقه‌ی عامل را، و اغلب خیلی بیشتر از آن را، می‌گرداند، تا شما فقط ابزارها و کار را بنویسید. از کوچک تا بزرگ هست. دو نمونه از Anthropic این گستره را خوب نشان می‌دهند.

tool runner بخشی از بسته‌ی anthropic است (در اواخرِ ۲۰۲۶ هنوز بتا). هر ابزار را مثلِ یک تابعِ معمولیِ پایتون می‌نویسید، با نوعِ ورودی‌ها و یک docstring، و آن را با دکوراتورِ @beta_tool نشانه می‌گذارید. SDK توضیح و اسکیمای ورودیِ ابزار را از همین‌ها می‌سازد. بعد tool_runner حلقه را می‌گرداند:

import anthropic
from anthropic import beta_tool
 
client = anthropic.Anthropic()
 
@beta_tool
def word_count(path: str) -> str:
    """Count the words in a text file.
 
    Args:
        path: The file's path.
    """
    return str(len(open(path).read().split()))
 
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=[word_count],
    messages=[{"role": "user", "content": "How many words are in notes.txt?"}],
)
for message in runner:
    print(message)

دکوراتور (decorator) همان خطِ @beta_tool بالای تابع است: تابع را به beta_tool می‌دهد، که دورش چیزهایی را که SDK لازم دارد می‌پیچد. ببینید چه چیزهایی را ننوشتید: نه tool_schemas، نه run_tool، نه حلقه‌ی while، نه جفت کردنِ tool_use_idها. هر دور، runner درخواست را می‌فرستد، ابزارهایی را که مدل خواسته اجرا می‌کند، نتیجه‌ها را پس می‌فرستد و پیامِ مدل را به شما می‌دهد. وقتی مدل دیگر ابزاری نخواهد، می‌ایستد. کاری که نمی‌کند همه‌ی کارهای دیگرِ mini است: نه پرسیدنِ اجازه، نه هوک، نه فایلِ دستورها، نه مهارت، نه فشرده‌سازی. این‌ها هنوز با خودِ شماست.

Claude Agent SDK سرِ دیگرِ این گستره است: هارنسِ خودِ Claude Code به شکلِ یک کتابخانه، برای پایتون (claude-agent-sdk) و TypeScript (@anthropic-ai/claude-agent-sdk). ابزارهایی که Claude Code برای خواندن، نوشتن و ویرایشِ فایل‌ها و اجرای فرمان به کار می‌برد، حلقه‌ی عامل، مدیریتِ زمینه همراهِ فشرده‌سازی، تنظیمِ اجازه‌ها و هوک‌ها، زیرعامل‌ها و اتصال به MCP، همه همراهش می‌آیند. مثلِ خودِ Claude Code، فایلِ CLAUDE.md و مهارت‌های پروژه را هم می‌خواند، مگر اینکه به او بگویید نخواند (با گزینه‌ی setting_sources). شما یک کار و چند تنظیم به آن می‌دهید و درونِ برنامه‌ی شما همان‌طور کار می‌کند که Claude Code.

هر کدام چه می‌دهد

این فهرستِ بخش‌های mini است، و اینکه هر کدام را چه کسی می‌نویسد:

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

انتخاب

از خودِ کار شروع کنید و کوچک‌ترین چیزی را بردارید که از پسش برمی‌آید:

• اصلاً عامل نه. اگر گام‌ها ثابت‌اند (دسته‌بندیِ هر ایمیل، خلاصه کردنِ هر گزارش)، یک فراخوانیِ API برای هر مورد در یک برنامه‌ی معمولی ارزان‌تر، سریع‌تر و آزمودنش آسان‌تر است. عامل برای وقتی است که مدل باید گام‌ها را خودش انتخاب کند.
• tool runner. چند ابزارِ خودتان را دارید و حلقه‌ی ساده همه‌ی چیزی است که لازم دارید: ربات پشتیبانی‌ای که سفارش‌ها را پیدا می‌کند، اسکریپتی که به پرسش‌ها درباره‌ی پایگاه‌داده‌تان جواب می‌دهد. ابزارها کاملاً در دستِ خودتان می‌مانند و حلقه برایتان آماده است.
• هارنسِ خودتان. کنترلی لازم دارید که کتابخانه‌ها نمی‌دهند: روالِ اجازه‌ای غیرمعمول، ابزارهایی که جای خاصی اجرا می‌شوند، برنامه‌ای کوچک بی‌هیچ وابستگیِ اضافه، یا اصلاً هدف یاد گرفتن است. mini همین است.
• Agent SDK. یک عاملِ جدی برای برنامه‌نویسی یا کار با فایل‌ها درونِ محصول یا روالِ کاریِ خودتان می‌خواهید: ویرایشِ فایلی که در برابرِ موردهای مرزیِ فراوان محکم شده، اجازه‌ها، هوک‌ها، فشرده‌سازی. ساختنِ درستِ همه‌ی این‌ها به دستِ خودتان ماه‌ها کار است.

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

مراقب باشید

Tool runner هنوز بتاست، و کتابخانه‌ها سریع‌تر از ایده‌های زیرشان عوض می‌شوند: نام‌ها، گزینه‌ها و پیش‌فرض‌ها از نسخه‌ای به نسخه‌ی دیگر جابه‌جا می‌شوند. نسخه‌ای را که به کار می‌برید ثابت کنید، پیش از ارتقا فهرستِ تغییراتش را بخوانید، و یک eval کوچک (از درسِ قبل) نگه دارید تا بعد از هر ارتقا اجرایش کنید.

امتحان کنید

اگر کلید دارید، مثالِ tool runner را در پوشه‌ای که یک notes.txt دارد اجرا کنید و هر message را که می‌دهد چاپ کنید. نوبت‌ها را بشمارید و با ردِ کارِ mini برای همین پرسش مقایسه کنید. بعد از خودتان بپرسید: کدام‌یک از محافظت‌های mini این‌جا نیست؟ (بخواهید کلمه‌های فایلی بیرون از پوشه را بشمارد.)

درست به کار بردن

1. کوچک‌ترین چیزی را بردارید که کار را انجام می‌دهد. چند گامِ ثابت چند فراخوانیِ API لازم دارد، نه یک عامل. چند ابزار یک tool runner لازم دارد، نه یک هارنسِ کامل.
2. بخش‌های محکم‌شده را آماده بردارید. ویرایشِ فایل، اجازه‌ها و فشرده‌سازی موردهای مرزیِ زیادی دارند. برای یک محصول، کدی را به کار ببرید که قبلاً با آن‌ها روبه‌رو شده است.
3. بدانید فریم‌ورک به‌جای شما چه تصمیمی می‌گیرد. وقتی کارِ عجیبی کرد، اگر بدانید کدام کار (حلقه، یک ابزار، زمینه، یک اجازه) درست انجام نمی‌شود، علت را زودتر پیدا می‌کنید.
4. نسخه‌ها را ثابت کنید و یک eval نگه دارید. ارتقای یک کتابخانه تغییری در عاملِ شماست و همان آزمونی را می‌خواهد که تغییرِ پرامپت.

واژه‌های این درس

• فریم‌ورکِ عامل (agent framework): کدِ آماده‌ای که حلقه‌ی عامل و اغلب بخشِ بیشتری از هارنس را می‌گرداند، تا شما ابزارها و کار را بنویسید
• tool runner: ابزارِ کمکیِ بسته‌ی anthropic که حلقه را دورِ تابع‌های ابزارِ خودتان می‌گرداند (client.beta.messages.tool_runner)
• Claude Agent SDK: هارنسِ Claude Code به شکلِ یک کتابخانه، با ابزارها، حلقه، مدیریتِ زمینه، اجازه‌ها و هوک‌هایش
• دکوراتور (decorator): خطی مثلِ @beta_tool بالای یک تابعِ پایتون، که تابع را به تابعِ دیگری می‌دهد تا دورش را بپیچد

ایده‌ی اصلی

هر فریم‌ورکِ عامل بخشی از کارهای mini را انجام می‌دهد، از فقط حلقه تا کلِ هارنس. کوچک‌ترین فریم‌ورکی را بردارید که به کار می‌خورد، و با آنچه ساختنِ mini به شما یاد داد بفهمید به‌جای شما چه می‌کند.