Bildirim Temelli API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Yayınlanma tarihi: 18 Mayıs 2026

Açıklayıcı Web Uzantılar Chrome Durumu Amaç
GitHub Geliştirici denemesi Geliştirici denemesi Geliştirici denemesi Geliştirici denemesi Görünüm Deneme Yapma Amacı (Intent to Experiment)

Bildirimsel API'yi kullanarak standart HTML formlarını WebMCP araçlarına dönüştürmek için ek açıklamalar ekleyin. Açıklamalar, <form> öğesinde aracın adını ve amacını tanımlarken alanlar araç parametreleri olarak işlev görür. Tarayıcı, bu öğeleri, ajanların zorunlu araçlara benzer şekilde kullanabileceği yapılandırılmış bir temsile çevirir.

Bu API'yi kullanmadan önce kullanım alanları örnekleri hakkında bilgi edinin.

Araç kaydı

Formunuza aşağıdaki HTML özelliklerini ekleyin:

  • toolname: Aracın adını amacına göre net bir şekilde belirtin.
  • tooldescription: Aracın hangi işlemi yaptığı ve amacını açıklayın.

Örneğin, aşağıdaki form example.com/get-customer-support adresinde bulunuyor:

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

Bir temsilci toolname numaralı telefonu aradığında tarayıcı, formu ön plana çıkarır ve alanını doldurur. Form, kullanıcı tarafından görünmeye devam eder.

toolname veya tooldescription HTML özelliğini kaldırırsanız araç kayıttan kaldırılır.

(İsteğe bağlı) Araç parametreleri

Doğruluğu artırmak için aşağıdaki HTML özelliklerini tek tek form öğelerine ekleyin:

  • toolparamdescription: Öğeleri JSON şemasındaki bir özellik açıklamasıyla eşleyin. Bu özellik olmadan tarayıcı, ilişkili <label> içindeki içeriği kullanır ve etiketlenebilir alt öğeleri atlar. Etiket yoksa tarayıcı aria-description öğesini referans alır.

Aşağıdaki formda, <select> öğesi için isteğe bağlı parametreler kullanılmaktadır.

<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>

Tarayıcı, bu formu aşağıdaki JSON ile temsil edilen bir araç olarak yorumlar:

[
  {
    "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"
      ]
    }
  }
]

Formu gönderin.

Form gönderme için iki seçeneğiniz vardır:

  • Kullanıcının görevi tamamlamak için Gönder'i manuel olarak tıklaması gerekir.
  • Gönderme işlemini ve gezinme değişikliğini tetiklemek için toolautosubmit ekleyin.

SubmitEvent arayüzünde agentInvoked boole özelliği kullanıma sunulur. Bu özellik, web uygulamanızın davranışını özellikle ajan tabanlı etkileşimlere uyarlamak için bir form yapay zeka ajanı tarafından her tetiklendiğinde doğru olarak ayarlanır.

Ayrıca SubmitEvent, respondWith(Promise<any>) yöntemini içerir. Böylece, formun sonuçlarıyla çözdüğünüz bir sözü tarayıcıya iletebilirsiniz. Elde edilen değer daha sonra serileştirilir ve aracın çıkışı olarak modele döndürülür. Bu yöntemi kullanmak için öncelikle tarayıcının standart form gönderme işlemini durdurmak üzere preventDefault() işlevini çağırmanız gerekir.

<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>

Tarayıcı, bir yapay zeka aracısının "toolactivated" etkinliğiyle bir aracı çalıştırdığına dair sinyaller gönderir. Bu, form alanları önceden doldurulduktan sonra pencerede tetiklenir. Aksine, bir kullanıcı aracılı işlemi iptal ederse veya reset() yöntemi çağrılırsa "toolcancel" etkinliği tetiklenir. Bu etkinliklerin ikisi de iptal edilemez ve tanımlama için toolName özelliği sağlar.

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.
});

Odak göstergesini değiştirme

Kullanıcıları ve aracıları sayfada nerede oldukları konusunda bilgilendirmek için görünür bir odak göstergesi çok önemlidir. Bir temsilci bir aracı başarıyla çağırdığında, ilişkili forma odaklandığında ve alanlarını otomatik olarak doldurduğunda tarayıcı, görsel geri bildirim için belirli CSS sözde sınıflarını tetikler:

  • :tool-form-active, aracın HTML form öğesine uygulanır.
  • :tool-submit-active, formun gönder düğmesine (varsa) uygulanır.

Bu sınıflar, form gönderildiğinde, temsilci işlemi iptal ettiğinde veya kullanıcı formu sıfırladığında devre dışı bırakılır. Bu durumlar için CSS'yi özelleştirebilir veya varsayılan tarayıcı stilini kullanabilirsiniz.

/* 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;
}

Odaklanmayla ilgili en iyi uygulamalar ve stil hakkında daha fazla bilgi edinin.

Etkileşim kurma ve geri bildirim paylaşma

WebMCP aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz ve geri bildiriminiz olursa lütfen bizimle paylaşın.