Deklaratywny interfejs API

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

Data publikacji: 18 maja 2026 r., ostatnia aktualizacja: 25 września 2026 r.

Film z wyjaśnieniem Sieć Rozszerzenia Stan Chrome Intencja
GitHub Testowanie origin Testowanie origin Wyświetl Zamiar przeprowadzenia eksperymentu

Użyj interfejsu Declarative API, aby przekształcić standardowe formularze HTML w narzędzia WebMCP, dodając adnotacje. Adnotacje definiują nazwę i przeznaczenie narzędzia w elemencie <form>, a pola pełnią funkcję parametrów 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, zapoznaj się z przykładami zastosowań.

Rejestracja narzędzia

Dodaj do formularza te atrybuty HTML:

  • toolname: nadaj narzędziu jasną nazwę, która będzie odzwierciedlać jego przeznaczenie.
  • tooldescription: opisz działanie narzędzia i jego przeznaczenie.

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

<form toolname="createSupportRequest" tooldescription="Submits a request for customer 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 mapy 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 elementu aria-description.

Poniższy formularz korzysta z 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
    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, które jest reprezentowane przez ten kod JSON:

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

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 wywołać przesłanie i nawigację, gdy model wywoła to narzędzie.

Interfejs SubmitEvent wprowadza atrybut logiczny agentInvoked. Ten atrybut ma wartość „true”, gdy formularz jest wywoływany przez agenta AI. Umożliwia to dostosowanie działania 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 document.modelContextmomencie, gdy pola formularza są wstępnie wypełnione. 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.

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

document.modelContext.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 agenty o tym, gdzie znajdują się na stronie. Gdy agentowi uda się wywołać narzędzie, skupić się na powiązanym formularzu i automatycznie wypełnić jego pola, przeglądarka wywoła określone pseudoklasy CSS, aby zapewnić wizualne informacje zwrotne:

  • :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ć 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 będziesz mieć jakieś uwagi, chętnie je poznamy.

Wstecz
Imperative API
Dalej
WebMCP a MCP