چیت‌شیت

استفاده از ابزار و کتابخانه‌های مهارت در ایجنت

Agent Tool Use and Skill Libraries

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

  • ۱۲ بخش
  • ۳ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. حلقه فراخوانی تابع
  2. اسکیمای ابزار
  3. مقایسه ارائه‌دهندگان در کنار هم
  4. وظایف در کد
  5. رجیستری با خطاهای ساختاریافته
  6. حلقه کتابخانه‌ی مهارت
  7. حلقه پالایش Voyager
  8. خرابی‌های اعتبارسنجی و راه‌حل‌ها
  9. پیش‌فرض‌ها در کد درس
  10. عددهایی که اهمیت دارند
  11. قوانین امنیتی
  12. پرسش‌ها

حلقه فراخوانی تابع

معماری
پیامپیام‌ها + تعریف‌های ابزارtool_callاجرانتیجهاسکیماهاکاربرپیامی ارسال می‌کندبرنامهابزارها را اجرا می‌کندمدلدرباره فراخوانی تصمیم می‌گیردابزارget_weather("Tokyo")تعریف‌های ابزاراسکیمای JSON

اسکیمای ابزار

کد
json
{"type": "function", "function": {
  "name": "get_weather",
  "description": "Get current weather for a city.",  # یک پرامپت برای انتخاب ابزار
  "parameters": {"type": "object",                   # Anthropic: input_schema
    "properties": {"city": {"type": "string"},
      "units": {"enum": ["celsius", "fahrenheit"]}},
    "required": ["city"]}}}                          # فیلد مفقود: مشاهده خطا

مقایسه ارائه‌دهندگان در کنار هم

مقایسه
عاملOpenAIAnthropicGoogle
پارامتر ابزارهاtoolstoolsfunction_declarations
فرمت فراخوانیtool_calls[].functioncontent[].type="tool_use"functionCall
فیلد اسکیماfunction.parametersinput_schemaاسکیمای JSON
فراخوانی اجباریtool_choice="required"tool_choice={"type":"any"}function_calling_config
نحوه بازگشت نتیجه{"role": "tool", "tool_call_id": ...}type: "tool_result" در یک پیام کاربردر جدول درس آورده نشده

وظایف در کد

کار و کد
وظیفهکد
ثبت یک ابزارreg.register(ToolDef(...))
نمایش کاتالوگ به مدلreg.catalog()
اجرای فراخوانی‌های یک نوبت گفت‌وگوreg.dispatch_many(calls)
بررسی آرگومان‌ها با یک اسکیماvalidate(args, schema)
اجرای حلقه با یک سقف مشخصrun_function_calling_loop(user_message, max_iterations=5)
یافتن مهارت‌ها برای یک وظیفهlib.search("I need a pickaxe")
اجرای یک مهارت همراه با وابستگی‌هایشlib.execute("craft_iron_pickaxe")
اجرای دموpython3 code/main.py

رجیستری با خطاهای ساختاریافته

کد
python
reg = ToolRegistry()
reg.register(ToolDef(name="classify", description="<when to use>",
    input_schema={"type": "object", "required": ["status"],
        "properties": {"status": {"type": "string",
            "enum": ["open", "closed", "pending"]}}},
    executor=classify))                                           # مقدار پیش‌فرض timeout_s برابر 5.0 است
calls = [ToolCall("u02", "multiply", {"a": "4", "b": 5}),         # تبدیل نوع خودکار "4"
         ToolCall("u03", "classify", {"status": "in_progress"})]  # در enum نیست
for result in reg.dispatch_many(calls):
    result.ok, result.content                                     # خطاها رشته هستند، هرگز raise نمی‌شوند

حلقه کتابخانه‌ی مهارت

کد
python
lib = SkillLibrary()
lib.register(Skill(name="craft_iron_pickaxe", description="<what it does>",
    code="mine_ore(); place_table(); craft('iron_pickaxe')",
    fn=_craft_iron_pick_v1, tags=("craft", "tool"),
    depends_on=("mine_ore", "place_crafting_table")))  # v1
lib.search("I need a pickaxe")                    # همپوشانی توکن، top_k=3
ctx = lib.execute("craft_iron_pickaxe")           # وابستگی‌ها اول، topo_order
ctx["failed"]                                     # True: نیاز به 2 stick، موجودی 0
lib.register(Skill(..., fn=_craft_iron_pick_v2))  # هم‌نام: v2

حلقه پالایش Voyager

گام‌به‌گام
  1. برنامه آموزشیوظیفه‌ای را پیشنهاد می‌دهد که کمی بالاتر از توانایی فعلی است.
  2. کتابخانهk مهارت برتر را بر اساس شباهت کوئری به توضیحات برمی‌گرداند.
  3. ایجنتمهارتی را به‌صورت کد اجرایی می‌نویسد یا ترکیب می‌کند.
  4. محیطمهارت را اجرا کرده و success، error یا self-verification failure برمی‌گرداند.
  5. ایجنتمهارت را با استفاده از سیگنال به عنوان زمینه بازنویسی می‌کند.
  6. کتابخانهنسخه جدید را ذخیره می‌کند. حلقه با موفقیت یا رسیدن به حداکثر دورها متوقف می‌شود.

خرابی‌های اعتبارسنجی و راه‌حل‌ها

عیب‌یابی
  • error: unknown tool 'subtract'

    علت
    مدل ابزاری را فراخوانی می‌کند که وجود ندارد
    راه‌حل
    برگرداندن خطا. اضافه کردن یک ابزار no-op برای امتناع
  • missing required: <name>

    علت
    فیلد اجباری وجود ندارد
    راه‌حل
    خطا را بازگردانید. مدل دوباره تلاش می‌کند
  • 'in_progress' not in [...]

    علت
    مقدار خارج از گزینه‌های enum است
    راه‌حل
    رد کردن با خطایی توصیفی
  • ابزار اشتباه انتخاب شده

    علت
    توضیحات نامناسب ابزار
    راه‌حل
    بیان کنید که ابزار چه می‌کند و چه زمانی باید از آن استفاده کرد
  • هدایت نتایج به فراخوانی‌های اشتباه

    علت
    جابه‌جا شدن مقادیر tool_use_id
    راه‌حل
    تطبیق هر نتیجه بر اساس شناسه (ID) آن
  • بدتر شدن کیفیت بازیابی

    علت
    حجم کتابخانه از چند صد مهارت فراتر رفته است
    راه‌حل
    اضافه کردن فیلترهای برچسب و محدودیت‌های قطعی

پیش‌فرض‌ها در کد درس

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
timeout_s5.0به ازای هر ابزار در ToolDef
version1Skill جدید
dedupTrueنام یکسان باعث پالایش مهارت می‌شود
top_k3نتایج جستجوی مهارت
tag_filterNoneتنظیم آن برای محدود کردن جستجو به یک برچسب
max_iterations5run_function_calling_loop

عددهایی که اهمیت دارند

مفهوم‌ها
بنچمارک BFCL V4
چهل درصد ایجنتی، 30% چند نوبتی، 10% زنده، 10% غیرزنده، 10% توهم.
فراخوانی‌های موازی
کاهش رفت‌وبرگشت‌ها از 2 به 1.
تاخیر در حالت موازی
60 تا 80% کمتر برای 5 تا 10 فراخوانی ابزار در هر کوئری.
بودجه فراخوانی
10 تا 20 فراخوانی در هر گفتگو معقول است.
وویجر (Voyager)
3.3 برابر آیتم‌های منحصربه‌فرد بیشتر، 8.5 برابر ابزارهای سنگی سریع‌تر، 6.4 برابر ابزارهای آهنی سریع‌تر.
تول‌فورمر (Toolformer)
نگه‌داشتن یک فراخوانی ابزار تنها زمانی که نتیجه آن تابع زیان (loss) توکن بعدی را کاهش دهد.

قوانین امنیتی

نکته‌ها
  • هرگز SQL تولیدشده توسط مدل را مستقیماً به دیتابیس ارسال نکنید. آن را پارامتری کنید.
  • توابع را در لیست مجاز (allowlist) قرار دهید. فقط ابزارهای موردنیاز کاربر را ارائه دهید.
  • تمام آرگومان‌ها را از نظر نوع، محدوده و فرمت اعتبارسنجی کنید.
  • نتایج ابزارها را پاکسازی کنید. کلیدهای API، اطلاعات شناسایی فردی (PII) و خطاهای داخلی را حذف کنید.
  • run_code کد را با ast.parse تجزیه می‌کند و وارد کردن ماژول‌ها و دسترسی‌های داندر (dunder) را مسدود می‌کند.
  • کد غیرقابل‌اعتماد را در یک فرایند یا کانتینر مجزا اجرا کنید.

پرسش‌ها

پرسش و پاسخ
چه کسی ابزار را اجرا می‌کند؟
کد شما. مدل فقط درباره اینکه چه چیزی فراخوانی شود تصمیم می‌گیرد.
خروجی‌های ساختاریافته یا فراخوانی تابع؟
خروجی‌های ساختاریافته برای استخراج داده. فراخوانی تابع برای عمل روی سیستم‌های خارجی.
چرا خطاها را به عنوان نتیجه برگردانیم؟
مدل‌ها با خطاهای ساختاریافته خود را اصلاح می‌کنند. آن‌ها با خطاهای خالی یا عمومی شکست می‌خورند.
مهارت چیست؟
قطعه‌ای کد دارای نام به همراه توضیحات، قابل بازیابی با شباهت معنایی.
چرا باید مهارت‌ها را نسخه‌بندی کرد؟
والد قفل‌شده روی v1، نسخه v3 فرزند را دریافت نمی‌کند.