Deklaratywny interfejs API

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

Opublikowano: 18 maja 2026 r.

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

Użyj deklaratywnego interfejsu 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 działają jako parametry narzędzia. Przeglądarka tłumaczy te elementy na uporządkowaną reprezentację, której agenci mogą używać podobnie jak narzędzi imperatywnych.

Zanim zaczniesz korzystać z tego interfejsu API, przeczytaj o przykładowych przypadkach użycia.

Rejestracja narzędzia

Dodaj do formularza te atrybuty HTML:

  • toolname: wyraźnie nazwij narzędzie 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 toolname, przeglądarka ustawi fokus na formularzu 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 te atrybuty HTML do poszczególnych elementów formularza:

  • toolparamdescription: mapuj elementy 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.

Ten formularz używa parametrów opcjonalnych dla 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

Masz 2 możliwości przesłania formularza:

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

Interfejs SubmitEvent wprowadza atrybut logiczny agentInvoked. Ten atrybut jest ustawiany na true, gdy formularz jest wywoływany przez agenta AI, aby dostosować działanie aplikacji internetowej specjalnie do interakcji opartych na agentach.

Dodatkowo SubmitEvent zawiera metodę respondWith(Promise<any>), dzięki czemu możesz przekazać przeglądarce 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>

Przeglądarka sygnalizuje, że agent AI wykonał narzędzie za pomocą zdarzenia "toolactivated". Jest ono wywoływane w oknie po wstępnym wypełnieniu pól formularza. Jeśli użytkownik anuluje operację agenta lub zostanie wywołana metoda reset(), zostanie wywołane zdarzenie "toolcancel". Oba te zdarzenia są nieanulowane 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.
});

Zmiana wskaźnika zaznaczenia

Widoczny wskaźnik zaznaczenia jest niezbędny, aby informować użytkowników i agentów o tym, gdzie znajdują się na stronie. Gdy agent pomyślnie wywoła narzędzie, ustawi fokus na powiązanym formularzu i automatycznie wypełni jego pola, przeglądarka wywoła określone pseudoklasy CSS w celu uzyskania wizualnej informacji zwrotnej:

  • :tool-form-active jest stosowana do elementu HTML form narzędzia.
  • :tool-submit-active jest stosowana do przycisku przesyłania formularza, jeśli jest on obecny.

Te klasy są dezaktywowane po przesłaniu formularza, anulowaniu działania przez agenta lub zresetowaniu formularza przez użytkownika. Możesz dostosować CSS dla tych stanów lub polegać na domyślnym 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;
}

Więcej informacji o sprawdzonych metodach i stylu zaznaczenia.

Zaangażuj się i prześlij opinię

WebMCP jest obecnie omawiany i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i masz jakieś uwagi, chętnie je poznamy.