Formulários agênticos

Recursos da Web: Atributos do WebMCP associados a formulários

A API Declarativa transforma elementos HTML <form> padrão em ferramentas do WebMCP usando atributos. O navegador sintetiza um esquema JSON com base nas entradas do formulário e processa as interações do agente.

Formulários de indicador do Angular: NÃO adicione toolname/tooldescription a formulários criados com form() de @angular/forms/signals. Em vez disso, adicione provideExperimentalWebMcpForms() aos provedores do app e transmita a opção experimentalWebMcpTool: { name, description } para form(). O Angular registra o formulário usando a API Imperative, criando o esquema com base no modelo de indicador e conectando-o à validação e ao envio. Usar as duas abordagens registra o mesmo formulário duas vezes.

Atributos do formulário

  • toolname: nome exclusivo da ferramenta.
  • tooldescription: o que a ferramenta faz e quando um agente deve usá-la. Não liste os campos, as opções ou os limites do formulário: o navegador já os inclui no esquema que cria com base nos controles do formulário.
  • toolautosubmit: (opcional) se presente, o agente pode enviar o formulário sem esperar pela interação do usuário.
  • toolparamdescription: (opcional) fornece uma maneira de definir uma descrição de propriedade no esquema JSON. Use-o para explicar o que o valor significa (por exemplo, com valores de amostra), não para repetir as opções ou os limites do controle.
    • Ordem de resolução: o navegador usa toolparamdescription, se presente. Na ausência dele, usa o textContent do <label> associado (pulando os descendentes que podem ser rotulados). Se não houver um rótulo, ele vai usar o aria-description.
    • Agrupamento (Fieldsets): para anexar uma descrição a um grupo de elementos relacionados (como botões <input type="radio">), coloque toolparamdescription no elemento pai <fieldset> mais próximo para que ele seja aplicado ao grupo de parâmetros como um todo.

Exemplo

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Como processar envios em JavaScript

Quando um agente envia o formulário, o SubmitEvent inclui agentInvoked (booleano) e respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Eventos de ciclo de vida

O document.modelContext emite eventos quando os agentes começam ou param de interagir com uma ferramenta: toolactivated é acionado quando a execução da ferramenta começa, e toolcancel é acionado quando ela é cancelada.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Feedback visual (CSS)

Use pseudoclasses para destacar formulários quando um agente interagir com eles:

  • :tool-form-active: aplicado ao elemento <form> usado ativamente pelo agente.
  • :tool-submit-active: aplicado ao botão de envio quando o navegador pausa para revisão do usuário (se toolautosubmit for omitido).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Adequação do formulário (quando evitar)

A API Declarative é ideal para formulários padrão independentes. Não é uma boa opção nestes cenários:

  • Campos altamente dependentes: formulários em que as entradas mudam as opções ou a visibilidade com base em outras entradas. O esquema sintetizado não consegue expressar bem essas dependências.
  • Componentes de interface personalizados: formulários que dependem de entradas não padrão (por exemplo, canvas, editores de rich text) que não serializam valores automaticamente.
  • Assistentes de várias etapas: fluxos de trabalho complexos que exigem vários envios de formulários. A API imperativa ou a interação padrão do DOM é mais adequada aqui.

Quando usar o toolautosubmit

  • Operações e consultas somente leitura: pesquisas, filtros, busca de detalhes ou verificação de status (por exemplo, pesquisa de um modelo de carro, pesquisa em um diretório, verificação de disponibilidade de estoque).
  • Ações reversíveis de baixo risco: ações de formulário que podem ser facilmente desfeitas ou refinadas pelo usuário manualmente (por exemplo, adicionar itens a um carrinho, aplicar um código de cupom, salvar um rascunho ou definir opções de layout temporárias).

Quando omitir toolautosubmit

  • Ações destrutivas ou irreversíveis: excluir registros, redefinir configurações do sistema ou limpar bancos de dados.
  • Ações financeiras e transacionais: enviar um formulário de finalização de compra, transferir fundos, autorizar pagamentos de assinaturas ou fazer pedidos finais.
  • Comunicação de alto impacto com o usuário: enviar uma candidatura final de emprego, enviar e-mails/mensagens para outros usuários reais ou publicar conteúdo voltado ao público.
  • Configurações de conta sensíveis: mudar senhas, modificar funções/permissões de usuário ou atualizar informações do perfil/faturamento.

Estratégias de fallback

A API declarativa do WebMCP é segura para uso em todos os navegadores. Os navegadores que não são compatíveis com o WebMCP vão ignorar os atributos tool*, e o <form> vai continuar funcionando como um formulário HTML normal. Não é necessário detectar recursos.