مرجع ابزارهای داخلی

Agent با مجموعه‌ای از ابزارهای داخلی عرضه می‌شود که هوش مصنوعی در طول گفتگوها به طور خودکار فراخوانی می‌کند. این ابزارها به طور پیش‌فرض در گفتگوهای ماندگار در دسترس هستند؛ توسعه‌دهندگان اسکریپت معمولاً نیازی به فراخوانی مستقیم آن‌ها ندارند — هوش مصنوعی بر اساس قصد کاربر ابزار مناسب را انتخاب می‌کند.

درک اینکه این ابزارها چه کاری می‌توانند انجام دهند به شما کمک می‌کند prompt های سیستم و ابزارهای سفارشی بهتری بنویسید.

دریافت داده وب

web_fetch

محتوای یک URL را دریافت کنید، با پشتیبانی از استخراج HTML-به-متن و خلاصه‌سازی LLM.

پارامتر	نوع	الزامی	توضیحات
url	string	بله	URL هدف (فقط http/https)
prompt	string	خیر	prompt خلاصه (وقتی داده شود، از یک LLM برای تقطیر محتوا استفاده می‌شود)
max_length	number	خیر	حداکثر کاراکتر محتوا

جزئیات رفتار:

• مهلت درخواست ۳۰ ثانیه
• محتوای HTML به طور خودکار متن بدنه اصلی را استخراج می‌کند (ناوبری، نوارهای کناری و غیره را حذف می‌کند)
• پاسخ‌های JSON به طور خودکار تجزیه می‌شوند
• متن ساده همان‌گونه که هست برگردانده می‌شود
• وقتی prompt داده شود، محتوای دریافت‌شده برای خلاصه‌سازی به یک LLM ارسال می‌شود

مقدار بازگشتی:

{
  "url": "https://example.com",
  "content_type": "text/html",
  "content": "Extracted body content...",
  "truncated": false,
  "final_url": "https://example.com/redirected"
}

web_search

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

پارامتر	نوع	الزامی	توضیحات
query	string	بله	کلمات کلیدی جستجو
max_results	number	خیر	حداکثر تعداد نتایج (پیش‌فرض ۵، سقف ۱۰)

موتورهای جستجوی پشتیبانی‌شده:

موتور	توضیحات	پیکربندی لازم
DuckDuckGo	موتور پیش‌فرض	هیچ
Bing	Microsoft Bing Search	کلید API لازم است
Baidu	جستجوی Baidu	بدون نیاز به کلید API
Google Custom Search	Google Custom Search	کلید API + شناسه CSE لازم است

موتورهای جستجو در صفحه مدیریت → Agent → تنظیمات پیکربندی می‌شوند.

مقدار بازگشتی:

[
  {
    "title": "Search result title",
    "url": "https://example.com/result",
    "snippet": "Result summary text..."
  }
]

get_tab_content

محتوای رندر شده صفحه یک تب مشخص را بخوانید، که به Markdown ساختاریافته با حاشیه‌نویسی انتخابگر CSS تبدیل می‌شود.

پارامتر	نوع	الزامی	توضیحات
tab_id	number	بله	شناسه تب
selector	string	خیر	انتخابگر CSS؛ فقط قسمت مطابق را استخراج کنید
prompt	string	خیر	prompt خلاصه
max_length	number	خیر	حداکثر کاراکتر محتوا

تفاوت با web_fetch: get_tab_content صفحه را همان‌گونه که قبلاً توسط مرورگر رندر شده می‌خواند (شامل محتوای JS پویا)، در حالی که web_fetch یک درخواست HTTP تازه انجام می‌دهد.

مقدار بازگشتی:

{
  "tab_id": 123,
  "url": "https://example.com",
  "title": "Page title",
  "content": "Structured content...",
  "truncated": false,
  "used_selector": "main"
}

مدیریت تب

list_tabs

تب‌های باز را پرس‌وجو کنید، با پشتیبانی از چند شرط فیلتر.

پارامتر	نوع	الزامی	توضیحات
url_pattern	string	خیر	تطبیق regex URL
title_pattern	string	خیر	تطبیق regex عنوان
active	boolean	خیر	فقط تب فعال را برگردانید
window_id	number	خیر	پنجره مشخص
audible	boolean	خیر	فقط تب‌هایی که در حال پخش صدا هستند را برگردانید

open_tab

یک تب جدید باز کنید، یا یک تب موجود را هدایت کنید.

پارامتر	نوع	الزامی	توضیحات
url	string	بله	URL هدف
tab_id	number	خیر	شناسه یک تب موجود (اگر داده شود، آن تب هدایت می‌شود؛ در غیر این صورت یک تب جدید باز می‌شود)
active	boolean	خیر	آیا آن را فعال کنید (پیش‌فرض true)
window_id	number	خیر	پنجره مشخص
wait_until_loaded	boolean	خیر	آیا منتظر پایان بارگذاری صفحه بمانید (پیش‌فرض true)

close_tab

یک تب را ببندید.

پارامتر	نوع	الزامی	توضیحات
tab_id	number	بله	شناسه تب

activate_tab

یک تب را فعال کنید و پنجره‌ای که در آن است را فوکوس کنید.

پارامتر	نوع	الزامی	توضیحات
tab_id	number	بله	شناسه تب

سیستم فایل (OPFS)

opfs_write

یک فایل در فضای کار بنویسید.

پارامتر	نوع	الزامی	توضیحات
path	string	بله	مسیر فایل
content	string	بله	محتوای فایل (دودویی URL داده پشتیبانی می‌شود)

opfs_read

یک فایل از فضای کار بخوانید. به طور پیش‌فرض نوع فایل به طور خودکار تشخیص داده می‌شود: فایل‌های متنی محتوای خود را برمی‌گردانند، فایل‌های دودویی یک URL blob برمی‌گردانند.

پارامتر	نوع	الزامی	توضیحات
path	string	بله	مسیر فایل
mode	string	خیر	"text" / "blob" / "auto" (پیش‌فرض) — حالت بازگشتی خاصی را اجباری می‌کند
offset	number	خیر	شماره خط شروع (مبتنی بر ۱)، فقط حالت متنی
limit	number	خیر	تعداد خطوط برای خواندن، فقط حالت متنی (پس از بیش از ۲۰۰ خط متن، صفحه‌بندی لازم است)

opfs_list

محتوای دایرکتوری را فهرست کنید.

پارامتر	نوع	الزامی	توضیحات
path	string	خیر	مسیر دایرکتوری (پیش‌فرض دایرکتوری ریشه)

opfs_delete

یک فایل یا دایرکتوری را حذف کنید.

پارامتر	نوع	الزامی	توضیحات
path	string	بله	مسیر فایل/دایرکتوری

تعامل با کاربر

ask_user

از کاربر یک سوال بپرسید، با پشتیبانی از ورودی آزاد یا انتخاب ساختاریافته.

پارامتر	نوع	الزامی	توضیحات
question	string	بله	سوال
options	string[]	خیر	فهرست انتخاب‌ها (وقتی داده شود، این یک سوال چندگزینه‌ای می‌شود)
multiple	boolean	خیر	آیا انتخاب‌های متعدد مجاز است (پیش‌فرض false)

مهلت زمانی: پس از ۵ دقیقه بدون پاسخ، { answer: null, reason: "timeout" } را برمی‌گرداند.

مقدار بازگشتی:

{ "answer": "The user's answer text" }

execute_script

کد جاوااسکریپت را در یک صفحه یا یک sandbox اجرا کنید.

پارامتر	نوع	الزامی	توضیحات
code	string	بله	کد جاوااسکریپت
target	string	بله	"page" یا "sandbox"
tab_id	number	خیر	کدام تب را هدف قرار دهید وقتی target برابر page است (پیش‌فرض تب فعال فعلی)؛ برای sandbox نادیده گرفته می‌شود

مقایسه محیط اجرا:

محیط	DOM	JS صفحه	URL blob افزونه	بهترین برای
target: "page" (همیشه دنیای MAIN)	بله	بله	خیر	خواندن/دستکاری DOM، فراخوانی توابع صفحه، خواندن متغیرهای صفحه
target: "sandbox"	خیر	خیر	خیر	محاسبات خالص

حالت page همیشه در دنیای MAIN صفحه اجرا می‌شود و window را با صفحه به اشتراک می‌گذارد — بنابراین نمی‌تواند به URLهای blob خود افزونه دسترسی پیدا کند (مثلاً آدرسی که opfs_read در حالت blob برمی‌گرداند). وقتی نیاز به کار با یک URL blob دارید به جای آن از یک SkillScript استفاده کنید.

زیرعامل‌ها

agent

یک زیرعامل مستقل برای مدیریت یک کار فرعی پیچیده ایجاد کنید.

پارامتر	نوع	الزامی	توضیحات
prompt	string	بله	توضیحات کار فرعی
description	string	خیر	یک برچسب کوتاه (چند کلمه، برای نمایش در رابط کاربری)
type	string	خیر	نوع زیرعامل (به زیر مراجعه کنید)، پیش‌فرض "general"
tab_id	number	خیر	شناسه تب برای دادن به زیرعامل؛ زیرعامل روی آن تب کار می‌کند

انواع زیرعامل:

نوع	توضیحات	ابزارهای موجود
researcher	بازیابی اطلاعات (فقط‌خواندنی)	web_search، web_fetch، خواندن محتوای صفحه
page_operator	اتوماسیون مرورگر	مدیریت تب، دستکاری DOM، تعامل با صفحه
general	عمومی (پیش‌فرض)	همه ابزارها

ویژگی‌ها:

• یک زیرعامل زمینه گفتگوی مستقل خود را دارد
• نمی‌تواند از ask_user یا agent استفاده کند (برای جلوگیری از بازگشت)
• رویدادهای یک زیرعامل از طریق sub_agent_event به گفتگوی والد منتقل می‌شوند

مدیریت کار

این گروه از ابزارها یک فهرست کار موقت در یک گفتگو را مدیریت می‌کنند (در حافظه، نه ماندگار).

create_task

پارامتر	نوع	الزامی	توضیحات
subject	string	بله	عنوان کار
description	string	خیر	توضیحات دقیق

update_task

پارامتر	نوع	الزامی	توضیحات
task_id	string	بله	شناسه کار
status	string	خیر	"pending" / "in_progress" / "completed"
subject	string	خیر	عنوان جدید
description	string	خیر	توضیحات جدید

list_tasks

بدون پارامتر؛ یک فهرست کوتاه از همه کارها را برمی‌گرداند.

ابزارهای مدیریت کار عمدتاً برای این هستند که هوش مصنوعی پیشرفت خود را در حین مدیریت کارهای پیچیده چندمرحله‌ای پیگیری کند؛ داده کار ماندگار نمی‌شود.