API declarativa

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

Publicado em: 18 de maio de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste para desenvolvedores Período de teste para desenvolvedores Teste para desenvolvedores Período de teste para desenvolvedores Ver Intenção de experimentar

Use a API Declarativa para transformar formulários HTML padrão em ferramentas do WebMCP adicionando anotações. As anotações definem o nome e a finalidade da ferramenta no elemento <form>, enquanto os campos atuam como parâmetros da ferramenta. O navegador traduz esses elementos em uma representação estruturada que os agentes podem usar de maneira semelhante às ferramentas imperativas.

Antes de usar essa API, leia sobre exemplos de casos de uso.

Registro de ferramentas

Adicione os seguintes atributos HTML ao formulário:

  • toolname: nomeie a ferramenta de acordo com a finalidade dela.
  • tooldescription: descreva a ação da ferramenta e a finalidade dela.

Por exemplo, o formulário a seguir está em example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

Quando um agente chama toolname, o navegador foca no formulário e preenche o campo dele. O formulário permanece visível para o usuário.

Se você remover o atributo HTML toolname ou tooldescription, a ferramenta será cancelada.

(Opcional) Parâmetros da ferramenta

Para melhorar a acurácia, adicione os seguintes atributos HTML a elementos de formulário individuais:

  • toolparamdescription: mapeia elementos para uma descrição de propriedade no esquema JSON. Sem esse atributo, o navegador usa o conteúdo no <label> associado e pula os descendentes que podem ser rotulados. Se não houver um rótulo, o navegador vai se referir ao aria-description.

O formulário a seguir usa os parâmetros opcionais do elemento <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>

O navegador interpreta esse formulário como uma ferramenta, representada pelo seguinte 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"
      ]
    }
  }
]

Enviar o formulário

Você tem duas opções para enviar o formulário:

  • O usuário precisa clicar manualmente em Enviar para concluir a tarefa.
  • Adicione toolautosubmit para acionar o envio e uma navegação quando o modelo invocar essa ferramenta.

A interface SubmitEvent apresenta o atributo booleano agentInvoked. Esse atributo é definido como "true" sempre que um formulário é acionado por um agente de IA, para adaptar o comportamento do seu web app especificamente para interações baseadas em agentes.

Além disso, o SubmitEvent inclui o método respondWith(Promise<any>), para que você possa transmitir uma promessa ao navegador que é resolvida com os resultados do formulário. O valor resultante é serializado e retornado ao modelo como a saída da ferramenta. Para usar esse método, primeiro chame preventDefault() para interromper o envio padrão de formulários do navegador.

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

O navegador sinaliza que um agente de IA executou uma ferramenta com o evento "toolactivated". Isso é acionado na janela quando os campos do formulário são pré-preenchidos. Por outro lado, se um usuário cancelar a operação de agente ou o método reset() for invocado, um evento "toolcancel" será acionado. Os dois eventos não podem ser cancelados e fornecem um atributo toolName para identificação.

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

Modificar o indicador de foco

Um indicador de foco visível é fundamental para informar aos usuários e agentes onde eles estão em uma página. Quando um agente invoca uma ferramenta, foca o formulário associado e preenche automaticamente os campos, o navegador aciona pseudoclasses CSS específicas para feedback visual:

  • :tool-form-active é aplicado ao elemento HTML form da ferramenta.
  • :tool-submit-active é aplicado ao botão de envio do formulário, se houver.

Essas classes são desativadas quando o formulário é enviado, o agente cancela a ação ou o usuário redefine o formulário. Você pode personalizar o CSS para esses estados ou usar um estilo padrão do navegador.

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

Saiba mais sobre as práticas recomendadas e o estilo de foco.

Engajamento e como compartilhar feedback

O WebMCP está em discussão e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, envie sua opinião.