Bildirim Temelli API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Yayın tarihi: 18 Mayıs 2026

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

Bildirimsel API'yi kullanarak standart HTML formlarını ek açıklamalar ekleyerek WebMCP araçlarına dönüştürün. Ek açıklamalar, aracın adını ve amacını <form> öğesinde tanımlarken alanlar araç parametreleri olarak işlev görür. Tarayıcı, bu öğeleri aracıları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 gerçekleştirdiğini ve amacını açıklayın.

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

<form toolname="createSupportRequest" tooldescription="Submits a request for customer 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 öğesine başvurur.

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 
    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 gösterilen bir araç olarak yorumlar:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "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.
  • Model bu aracı çağırdığında gönderimi ve gezinmeyi 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. Bu nedenle, tarayıcıya formun sonuçlarıyla çözdüğünüz bir söz verebilirsiniz. Ortaya çıkan değer daha sonra serileştirilir ve aracın çıkışı olarak modele döndürülür. Bu yöntemi kullanmak için önce tarayıcının standart form gönderimini durdurmak üzere preventDefault() yöntemini ç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ı, "toolactivated" etkinliğiyle bir yapay zeka aracısının bir aracı yürüttüğünü belirtir. Bu etkinlik, form alanları önceden doldurulduktan sonra pencerede tetiklenir. Bunun tersine, 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ğini 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 temsilcileri bir 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 geri bildiriminizi bizimle paylaşmanızı rica ederiz.