Deklaratywny interfejs API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Data publikacji: 18 maja 2026 r.

Wyjaśnienie Sieć Rozszerzenia Stan Chrome Intencja
GitHub Wersja próbna dla deweloperów Okres próbny dla deweloperów Wersja próbna dla deweloperów Okres próbny dla deweloperów Wyświetl Zamiar przeprowadzenia eksperymentu

Użyj interfejsu Declarative API, aby przekształcić standardowe formularze HTML w narzędzia WebMCP, dodając adnotacje. Adnotacje określają nazwę i przeznaczenie narzędzia w elemencie <form>, a pola pełnią funkcję parametrów narzędzia. Przeglądarka tłumaczy te elementy na strukturalną reprezentację, której agenci mogą używać podobnie jak narzędzi imperatywnych.

Zanim zaczniesz korzystać z tego interfejsu API, zapoznaj się z przykładami zastosowań.

Rejestracja narzędzia

Dodaj do formularza te atrybuty HTML:

  • toolname: nadaj narzędziu jasną nazwę na podstawie jego przeznaczenia.
  • tooldescription: opisz działanie narzędzia i jego przeznaczenie.

Na przykład ten formularz znajduje się pod adresem example.com/get-customer-support:

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

Gdy agent wywoła funkcję toolname, przeglądarka wyświetli formularz i wypełni jego pole. Formularz pozostanie widoczny dla użytkownika.

Jeśli usuniesz atrybut HTML toolname lub tooldescription, narzędzie zostanie wyrejestrowane.

(Opcjonalnie) Parametry narzędzia

Aby zwiększyć dokładność, dodaj do poszczególnych elementów formularza te atrybuty HTML:

  • toolparamdescription: mapowanie elementów na opis właściwości w schemacie JSON. Bez tego atrybutu przeglądarka używa treści w powiązanym elemencie <label> i pomija elementy podrzędne, które można oznaczyć etykietą. Jeśli nie ma etykiety, przeglądarka odwołuje się do aria-description.

Poniższy formularz używa opcjonalnych parametrów elementu <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>

Przeglądarka interpretuje ten formularz jako narzędzie reprezentowane przez ten kod 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"
      ]
    }
  }
]

Wyślij formularz

Formularz możesz przesłać na 2 sposoby:

  • Aby wykonać to zadanie, użytkownik musi ręcznie kliknąć Prześlij.
  • Dodaj toolautosubmit, aby uruchomić przesłanie i zmianę nawigacji.

Interfejs SubmitEvent wprowadza atrybut logiczny agentInvoked. Ten atrybut ma wartość „true”, gdy formularz jest wywoływany przez agenta AI, co pozwala dostosować działanie aplikacji internetowej do interakcji z agentem.

Dodatkowo interfejs SubmitEvent zawiera metodę respondWith(Promise<any>), dzięki czemu możesz przekazać do przeglądarki obietnicę, którą rozwiążesz za pomocą wyników formularza. Wynikowa wartość jest następnie serializowana i zwracana do modelu jako dane wyjściowe narzędzia. Aby użyć tej metody, musisz najpierw wywołać preventDefault(), aby zatrzymać standardowe przesyłanie formularza przez przeglądarkę.

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

Sygnały przeglądarki, że agent AI wykonał narzędzie ze zdarzeniem "toolactivated". Zdarzenie jest wywoływane w oknie po wstępnym wypełnieniu pól formularza. Jeśli użytkownik anuluje operację agenta lub wywoła metodę reset(), zostanie wywołane zdarzenie "toolcancel". Oba te zdarzenia są nieodwoływalne i zawierają atrybut toolName do identyfikacji.

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

Modyfikowanie wskaźnika zaznaczenia

Widoczny wskaźnik fokusu jest niezbędny, aby informować użytkowników i programy, gdzie znajdują się na stronie. Gdy pracownik obsługi klienta pomyślnie wywoła narzędzie, skupi się na powiązanym formularzu i automatycznie wypełni jego pola, przeglądarka wywoła określone pseudoklasy CSS w celu przekazania wizualnej informacji zwrotnej:

  • :tool-form-active jest stosowany do elementu HTML form narzędzia.
  • :tool-submit-active jest stosowany do przycisku przesyłania formularza, jeśli taki przycisk występuje.

Te klasy są dezaktywowane po przesłaniu formularza, anulowaniu działania przez agenta lub zresetowaniu formularza przez użytkownika. Możesz dostosować kod CSS dla tych stanów lub skorzystać z domyślnego stylu przeglądarki.

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

Dowiedz się więcej o sprawdzonych metodach i stylu.

Zaangażuj się i prześlij opinię

WebMCP jest obecnie przedmiotem dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i chcesz podzielić się opinią, chętnie ją poznamy.