API اعلانی

الکساندرا کلپر
Alexandra Klepper
GitHub Bluesky

منتشر شده: ۱۸ مه ۲۰۲۶

توضیح دهنده وب افزونه‌ها وضعیت کروم قصد
گیت‌هاب نسخه آزمایشی توسعه‌دهنده نسخه آزمایشی توسعه‌دهنده نسخه آزمایشی توسعه‌دهنده نسخه آزمایشی توسعه‌دهنده مشاهده قصد آزمایش

از API اعلانی برای تبدیل فرم‌های استاندارد HTML به ابزارهای WebMCP با اضافه کردن حاشیه‌نویسی‌ها استفاده کنید. حاشیه‌نویسی‌ها نام و هدف ابزار را در عنصر <form> تعریف می‌کنند، در حالی که فیلدها به عنوان پارامترهای ابزار عمل می‌کنند. مرورگر این عناصر را به یک نمایش ساختاریافته ترجمه می‌کند که عامل‌ها می‌توانند مشابه ابزارهای دستوری از آن استفاده کنند.

قبل از استفاده از این API، موارد استفاده از آن را مطالعه کنید.

ثبت ابزار

ویژگی‌های HTML زیر را به فرم خود اضافه کنید:

  • toolname : نام ابزار را به طور واضح و بر اساس هدف آن بنویسید.
  • tooldescription : شرح دهید که ابزار چه کاری انجام می‌دهد و هدف آن چیست.

برای مثال، فرم زیر در example.com/get-customer-support قرار دارد:

<form toolname="supportRequestTool" tooldescription="Submit a request for support.">
</form>

وقتی یک عامل، toolname فراخوانی می‌کند، مرورگر فرم را در فوکوس قرار می‌دهد و فیلد آن را پر می‌کند. فرم برای کاربر قابل مشاهده باقی می‌ماند.

اگر هر یک از ویژگی‌های HTML toolname یا tooldescription را حذف کنید، ابزار از حالت ثبت خارج می‌شود.

(اختیاری) پارامترهای ابزار

برای بهبود دقت، ویژگی‌های HTML زیر را به عناصر فرم اضافه کنید:

  • toolparamdescription : عناصر را به یک توصیف ویژگی در JSON Schema نگاشت می‌کند. بدون این ویژگی، مرورگر از محتوای درون <label> مرتبط استفاده می‌کند و از زیرمجموعه‌هایی که قابلیت برچسب‌گذاری دارند، صرف نظر می‌کند. اگر برچسبی وجود نداشته باشد، مرورگر به aria-description مراجعه می‌کند.

فرم زیر از پارامترهای اختیاری برای عنصر <select> استفاده می‌کند.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required toolparamtitle="Support type" 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

مرورگر این فرم را به عنوان یک ابزار تفسیر می‌کند که توسط JSON زیر نمایش داده می‌شود:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

فرم را ارسال کنید

شما برای ارسال فرم دو انتخاب دارید:

  • کاربر باید برای تکمیل کار، به صورت دستی روی ارسال کلیک کند.
  • toolautosubmit برای شروع ارسال و تغییر ناوبری اضافه کنید.

رابط SubmitEvent ویژگی بولی agentInvoked را معرفی می‌کند. این ویژگی هر زمان که یک فرم توسط یک عامل هوش مصنوعی فعال شود، روی true تنظیم می‌شود تا رفتار برنامه وب شما را به طور خاص برای تعاملات مبتنی بر عامل تطبیق دهد.

علاوه بر این، SubmitEvent شامل متد respondWith(Promise<any>) است، بنابراین می‌توانید یک promise را به مرورگر ارسال کنید که با نتایج فرم آن را حل می‌کنید. سپس مقدار حاصل سریالی شده و به عنوان خروجی ابزار به مدل بازگردانده می‌شود. برای استفاده از این متد، ابتدا باید preventDefault() را فراخوانی کنید تا ارسال فرم استاندارد مرورگر متوقف شود.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

مرورگر با رویداد "toolactivated" اعلام می‌کند که یک عامل هوش مصنوعی ابزاری را اجرا کرده است. این رویداد پس از پر شدن فیلدهای فرم از قبل، در پنجره فعال می‌شود. برعکس، اگر کاربر عملیات عامل را لغو کند یا متد reset() فراخوانی شود، رویداد "toolcancel" فعال می‌شود. هر دوی این رویدادها غیرقابل لغو هستند و یک ویژگی toolName برای شناسایی ارائه می‌دهند.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

اصلاح نشانگر فوکوس

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

  • :tool-form-active به عنصر form HTML ابزار اعمال می‌شود.
  • :tool-submit-active در صورت وجود دکمه ارسال فرم، روی آن اعمال می‌شود.

این کلاس‌ها پس از ارسال فرم، لغو عملیات توسط عامل یا ریست شدن فرم توسط کاربر غیرفعال می‌شوند. می‌توانید CSS را برای این حالت‌ها سفارشی کنید یا از استایل پیش‌فرض مرورگر استفاده کنید.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

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

مشارکت کنید و بازخورد خود را به اشتراک بگذارید

WebMCP در حال حاضر در دست بررسی است و ممکن است در آینده تغییر کند. اگر این API را امتحان کردید و بازخوردی داشتید، خوشحال می‌شویم آن را بشنویم.