چیتشیت
استفاده از ابزار و کتابخانههای مهارت در ایجنت
Agent Tool Use and Skill Libraries
تعریف، اعتبارسنجی، توزیع و امنسازی فراخوانیهای ابزار. ذخیره مهارتها بهصورت کد، بازیابی، ترکیب و پالایش آنها.
فهرست مطالب
حلقه فراخوانی تابع
معماریاسکیمای ابزار
کد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"]}}} # فیلد مفقود: مشاهده خطا
مقایسه ارائهدهندگان در کنار هم
مقایسه| عامل | OpenAI | Anthropic | |
|---|---|---|---|
| پارامتر ابزارها | tools | tools | function_declarations |
| فرمت فراخوانی | tool_calls[].function | content[].type="tool_use" | functionCall |
| فیلد اسکیما | function.parameters | input_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
گامبهگام- برنامه آموزشیوظیفهای را پیشنهاد میدهد که کمی بالاتر از توانایی فعلی است.
- کتابخانهk مهارت برتر را بر اساس شباهت کوئری به توضیحات برمیگرداند.
- ایجنتمهارتی را بهصورت کد اجرایی مینویسد یا ترکیب میکند.
- محیطمهارت را اجرا کرده و
success،errorیاself-verification failureبرمیگرداند. - ایجنتمهارت را با استفاده از سیگنال به عنوان زمینه بازنویسی میکند.
- کتابخانهنسخه جدید را ذخیره میکند. حلقه با موفقیت یا رسیدن به حداکثر دورها متوقف میشود.
خرابیهای اعتبارسنجی و راهحلها
عیبیابیerror: unknown tool 'subtract'- علت
- مدل ابزاری را فراخوانی میکند که وجود ندارد
- راهحل
- برگرداندن خطا. اضافه کردن یک ابزار no-op برای امتناع
missing required: <name>- علت
- فیلد اجباری وجود ندارد
- راهحل
- خطا را بازگردانید. مدل دوباره تلاش میکند
'in_progress' not in [...]- علت
- مقدار خارج از گزینههای enum است
- راهحل
- رد کردن با خطایی توصیفی
ابزار اشتباه انتخاب شده
- علت
- توضیحات نامناسب ابزار
- راهحل
- بیان کنید که ابزار چه میکند و چه زمانی باید از آن استفاده کرد
هدایت نتایج به فراخوانیهای اشتباه
- علت
- جابهجا شدن مقادیر
tool_use_id - راهحل
- تطبیق هر نتیجه بر اساس شناسه (ID) آن
بدتر شدن کیفیت بازیابی
- علت
- حجم کتابخانه از چند صد مهارت فراتر رفته است
- راهحل
- اضافه کردن فیلترهای برچسب و محدودیتهای قطعی
پیشفرضها در کد درس
پیشفرضها| تنظیم | پیشفرض | نکته |
|---|---|---|
timeout_s | 5.0 | به ازای هر ابزار در ToolDef |
version | 1 | Skill جدید |
dedup | True | نام یکسان باعث پالایش مهارت میشود |
top_k | 3 | نتایج جستجوی مهارت |
tag_filter | None | تنظیم آن برای محدود کردن جستجو به یک برچسب |
max_iterations | 5 | run_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 فرزند را دریافت نمیکند.