API declarativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Publicado em: 18 de maio de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste para desenvolvedores Teste do desenvolvedor Teste para desenvolvedores Teste do desenvolvedor Ver Intenção de teste

Use a API Declarativa para transformar formulários HTML padrão em ferramentas WebMCP adicionando anotações. As anotações definem o nome e a finalidade da ferramenta no <form> elemento, 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 a ferramentas imperativas.

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

Registro de ferramentas

Adicione os seguintes atributos HTML ao formulário:

  • toolname: nomeie claramente a ferramenta com base na finalidade dela.
  • tooldescription: descreva qual ação a ferramenta realiza e a finalidade dela.

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

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

Quando um agente chama toolname, o navegador coloca o formulário em foco 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: mapeie elementos para uma descrição de propriedade no esquema JSON. Sem esse atributo, o navegador usa o conteúdo no <label> associado e ignora os descendentes que podem ser rotulados. Se não houver um rótulo, o navegador vai se referir à aria-description.

O formulário a seguir usa os parâmetros opcionais para o <select> elemento.

<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 o envio de formulários:

  • O usuário precisa clicar manualmente em Enviar para concluir a tarefa.
  • Adicione toolautosubmit para acionar o envio e uma mudança de navegação.

A interface SubmitEvent apresenta o atributo booleano agentInvoked. Esse atributo é definido como verdadeiro sempre que um formulário é acionado por um agente de IA, para adaptar o comportamento do app da Web 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 de formulário padrão 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 "toolactivated" evento. Isso é acionado na janela quando os campos do formulário são preenchidos automaticamente. Por outro lado, se um usuário cancelar a operação do agente ou o método reset() for invocado, um "toolcancel" evento será acionado. Esses 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 usuários e agentes onde eles estão em uma página. Quando um agente invoca uma ferramenta, concentra 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. É possível personalizar o CSS para esses estados ou usar um estilo de navegador padrão.

/* 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 ativa e está sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, gostaríamos de recebê-lo.