WebMCP e ClientTools: quando o chat passa a operar a interface

Durante muito tempo, colocar um LLM dentro de um produto significou colocar um chat ao lado da interface.

O usuário podia perguntar como cadastrar um veículo, e o modelo respondia com uma lista de passos. Podia pedir ajuda no onboarding, e o modelo explicava onde clicar. Podia perguntar onde estava um ativo, e o modelo descrevia o caminho até o mapa.

Era útil, mas existia uma fronteira clara. O chat conhecia palavras. A aplicação conhecia ações.

Essa fronteira começou a desaparecer com ferramentas executadas no cliente. Em vez de ensinar o usuário a operar cada tela, o agente pode chamar funções estruturadas que navegam, preenchem, selecionam e atualizam a própria interface. A pessoa continua vendo o que acontece e mantém o controle, mas deixa de traduzir uma intenção em uma sequência de cliques.

Foi isso que encontrei ao experimentar WebMCP e ClientTools em uma aplicação real. O resultado mais interessante não foi um chat mais inteligente. Foi perceber que a interface pode se tornar parte do ambiente de execução do agente.

O problema dos agentes que clicam às cegas

Um agente de navegador tradicional enxerga a interface mais ou menos como uma pessoa: lê o DOM, tenta entender textos, procura botões e simula cliques.

Isso funciona, mas é uma base frágil para produto.

Um botão pode mudar de posição. Um texto pode ser traduzido. Um componente pode renderizar depois de uma requisição. Duas opções podem ter nomes parecidos. Um modal pode cobrir o elemento que o agente pretendia usar. Cada etapa abre espaço para uma interpretação errada.

O problema cresce com a complexidade. Para localizar um veículo em um mapa, por exemplo, o agente talvez precise abrir a página certa, escolher uma aba, limpar um filtro, preencher a busca, esperar os dados, selecionar uma linha e só então verificar se o mapa focou no ponto correto.

O usuário pensa em uma intenção:

Localize o veículo ABC1D23 e esconda os eventos de hoje.

O DOM oferece uma coreografia.

Uma ferramenta oferece um contrato:

searchVehicles({ query: 'ABC1D23' })
focusVehicle({ deviceId: 'device-123' })
setMapLayers({ todayEvents: false })

Essa diferença parece pequena, mas muda a confiabilidade. O agente deixa de adivinhar como a interface funciona e passa a usar capacidades que a própria aplicação decidiu expor.

O que WebMCP propõe

WebMCP é uma proposta de API para aplicações web oferecerem ferramentas JavaScript a agentes de IA. No formato imperativo, a página registra uma ferramenta com nome, descrição, JSON Schema e uma função de execução. O agente descobre o contrato, escolhe quando usá-lo e recebe um resultado estruturado.

await document.modelContext.registerTool({
  name: 'focus_vehicle',
  description: 'Seleciona um veículo visível e centraliza o mapa nele.',
  inputSchema: {
    type: 'object',
    properties: {
      deviceId: { type: 'string' },
    },
    required: ['deviceId'],
    additionalProperties: false,
  },
  execute: async ({ deviceId }) => {
    // Usa as mesmas ações e regras da interface.
    return JSON.stringify({ ok: true, deviceId })
  },
})

Existe também uma API declarativa voltada a formulários HTML. A ideia nos dois casos é parecida: o site declara o propósito da ação, seus dados de entrada e seu comportamento, em vez de obrigar o agente a inferir tudo a partir da apresentação visual.

O detalhe que considero mais importante é que a ferramenta roda no contexto da página. Ela pode usar o estado já carregado, as permissões da pessoa autenticada, a rota atual e as mesmas funções usadas pelos componentes. O resultado também aparece na interface que a pessoa está vendo.

Isso cria um modelo de colaboração mais interessante do que automação invisível. O agente age no produto. O usuário acompanha o efeito.

ClientTools resolve o mesmo problema por outro caminho

ClientTools, no Mastra Client SDK, permite definir ferramentas cuja execução acontece no navegador. O contrato é enviado ao agente junto com a conversa. Quando o modelo chama uma ferramenta, o código roda no cliente, o resultado volta para o agente e a resposta continua.

const focusVehicle = createTool({
  id: 'focus_vehicle',
  description: 'Seleciona um veículo visível e centraliza o mapa nele.',
  inputSchema: z.object({ deviceId: z.string() }),
  outputSchema: z.object({ ok: z.boolean() }),
  execute: async ({ deviceId }) => {
    focusDeviceOnMap(deviceId)
    return { ok: true }
  },
})

await agent.stream(prompt, {
  clientTools: { focus_vehicle: focusVehicle },
})

WebMCP e ClientTools não são a mesma tecnologia. WebMCP procura criar um mecanismo da plataforma web que agentes de navegador possam descobrir. ClientTools é um mecanismo do framework para oferecer funções locais ao agente conectado à aplicação.

Mas os dois compartilham uma ideia poderosa: certas capacidades pertencem ao navegador, porque dependem do estado e da experiência que existem ali.

Um contrato, dois caminhos

No experimento que construí, a página de monitoramento expunha cinco capacidades:

• ler o estado atual da tela;
• pesquisar veículos sem perder os outros filtros;
• selecionar um veículo e focá-lo no mapa;
• mostrar ou esconder trajeto e eventos;
• pesquisar um local salvo e focar sua geofence.

A aplicação também expunha ferramentas globais para listar páginas disponíveis e navegar até uma delas, sempre respeitando permissões, feature flags e o estado da conta.

O primeiro desenho usava apenas WebMCP. Isso funcionava para um agente integrado ao navegador, mas o assistente do próprio produto conversava com um agente Mastra no backend. O backend não descobria automaticamente as ferramentas registradas na página.

A solução foi um adaptador. Ele descobre os descritores WebMCP, converte esses contratos em ClientTools e delega a execução novamente para a página.

agente do navegador ──> WebMCP ───────────────┐
                                               ├──> ação da feature ──> interface
chat do produto ──────> Mastra ──> ClientTool ─┘

O ponto importante é a implementação única. Regra de permissão, validação, busca, seleção e efeito visual continuam na feature. O adaptador cuida de descoberta, transporte e conversão de resultados.

Sem isso, dois caminhos que deveriam fazer a mesma coisa começam a divergir. O WebMCP passa a aceitar um argumento que o chat não aceita. Uma permissão é verificada num lado e esquecida no outro. O botão muda o estado de uma forma, enquanto a ferramenta muda de outra.

Uma ferramenta de interface precisa ser apenas outra entrada para a mesma capacidade do produto.

Onboarding deixa de ser um tour de slides

A aplicação mais óbvia dessa ideia é onboarding.

Onboardings tradicionais tentam antecipar uma sequência média. Mostram um modal, destacam cinco elementos e esperam que aquela ordem corresponda ao que a pessoa quer fazer. Normalmente o usuário fecha tudo no segundo passo.

Um onboarding conduzido por um agente pode começar pela intenção:

Quero configurar a operação para acompanhar entregas na Zona Sul.

A partir disso, o agente pode listar o que falta, navegar até a tela correta, abrir um cadastro, preencher campos já informados, pedir apenas os dados ausentes e mostrar uma prévia antes de confirmar.

O fluxo deixa de ser uma apresentação e vira uma conversa conectada ao produto.

Isso não significa dar ao LLM liberdade irrestrita para clicar em tudo. Significa oferecer ferramentas pequenas e explícitas, como list_setup_steps, open_vehicle_form, fill_vehicle_draft e submit_vehicle, cada uma com seus limites.

A separação entre rascunho e confirmação é especialmente útil. O agente pode preencher e validar sem produzir um efeito irreversível. A pessoa revisa. Só então uma ferramenta consequente conclui o cadastro.

Cadastros ficam conversacionais sem perder estrutura

Formulários continuam sendo uma ótima interface para dados estruturados. O problema é exigir que a pessoa descubra sozinha quais campos importam, em que ordem e com quais dependências.

Com ferramentas de cliente, o LLM pode coletar as informações em linguagem natural e mapeá-las para o formulário real. A aplicação continua responsável por máscara, validação, opções permitidas e mensagens de erro.

Imagine o pedido:

Cadastre a van de placa ABC1D23, modelo 2024, no grupo Operação SP. Ainda não tenho motorista.

O agente pode:

1. abrir o formulário de veículo;
2. preencher placa, ano e grupo;
3. consultar as opções válidas para campos dependentes;
4. deixar a associação de motorista vazia de forma explícita;
5. mostrar a revisão e pedir confirmação;
6. enviar o cadastro pela mesma ação usada pelo formulário.

O LLM ajuda a interpretar a intenção. O produto preserva o contrato dos dados.

Mapas deixam claro por que o DOM não basta

Mapas são um dos melhores exemplos para esse modelo porque grande parte da interação não tem uma representação simples no DOM.

Selecionar um marcador, mudar o zoom, acompanhar um veículo, alternar camadas ou desenhar uma geofence envolve coordenadas, estado interno, permissões e efeitos assíncronos. Pedir que um agente reproduza gestos de mouse sobre pixels é possível, mas pouco confiável.

Uma ferramenta pode receber a intenção em dados:

createGeofence({
  name: 'Centro de distribuição',
  center: { lat: -23.5505, lng: -46.6333 },
  radiusInMeters: 750,
  category: 'OPERATION',
})

Antes de criar, outra ferramenta pode mostrar o rascunho no mapa. A pessoa vê o círculo, ajusta o raio e confirma. O agente não precisa saber em qual pixel começa uma geofence. Precisa conhecer o contrato geográfico e o objetivo do usuário.

No meu experimento inicial, as ferramentas já conseguiam pesquisar veículos e locais, focar o mapa e controlar camadas. Criar e editar geofences é o próximo passo natural, desde que passe por permissão, prévia e confirmação.

Há muitos outros casos de uso

Quando uma aplicação começa a tratar suas ações como ferramentas, outros fluxos aparecem rapidamente:

• suporte que abre o diagnóstico correto e coleta os sinais técnicos da tela;
• configuração de alertas a partir de uma regra descrita em linguagem natural;
• montagem de filtros e dashboards sem obrigar o usuário a conhecer todas as dimensões;
• importações que explicam erros por linha e permitem corrigir apenas os campos inválidos;
• operações em lote que começam como uma prévia e exigem confirmação antes da execução;
• navegação contextual que leva a pessoa à área certa sem depender da estrutura do menu;
• acessibilidade, oferecendo outra forma de operar controles visuais complexos.

O padrão se repete: intenção em linguagem natural, decisão do agente, chamada tipada, execução pela aplicação e resultado visível.

O desenho da ferramenta importa mais que o modelo

Um modelo melhor não corrige uma ferramenta ambígua.

Se search mistura leitura e mutação, o agente não sabe qual efeito esperar. Se select_item aceita nome, índice ou ID sem dizer a prioridade, a execução fica probabilística. Se todo erro vira something_went_wrong, o modelo não sabe se deve refinar a busca, pedir permissão ou parar.

As ferramentas que funcionaram melhor seguiram algumas regras:

• nomes descrevem uma capacidade, não um elemento visual;
• schemas aceitam apenas os argumentos necessários;
• cada propriedade explica o significado esperado pelo modelo;
• buscas ambíguas retornam candidatos, sem escolher silenciosamente;
• resultados distinguem solicitação de efeito e efeito concluído;
• erros têm códigos úteis, como access_denied, ambiguous_place ou select_vehicle_first;
• ações idempotentes dizem claramente que true mostra e false esconde;
• a disponibilidade acompanha a rota e o ciclo de vida da interface.

Esse último ponto evita um erro perigoso. Se o usuário saiu do mapa, a ferramenta de controlar camadas não deveria continuar disponível só porque foi registrada no início da conversa. A superfície de ferramentas precisa representar o contexto atual.

Permissão e confirmação fazem parte do contrato

Executar no navegador não torna uma ação automaticamente segura.

A ferramenta precisa respeitar a mesma autorização da interface. Se a pessoa não pode visualizar geofences, o agente também não pode. Se um filtro de frota limita os veículos visíveis, uma busca por ferramenta não pode atravessar esse limite. Se a ação cria, exclui, compra ou envia algo, o produto precisa tratar isso como uma ação consequente.

Eu separaria as ferramentas em três grupos:

Também é importante não repetir automaticamente uma ferramenta consequente depois de uma falha de transporte. A ação pode ter sido executada, mesmo que o resultado não tenha chegado. Repetir por conta própria transforma uma incerteza em duplicidade.

Cancelamento e troca de contexto merecem o mesmo cuidado. Se a pessoa muda de frota, fecha a conversa ou sai da página, execuções pendentes precisam ser canceladas e resultados atrasados não podem alterar o novo contexto.

Ainda é cedo para WebMCP

No momento em que escrevo, WebMCP é um Draft Community Group Report, não um padrão W3C final, e continua sujeito a mudanças. O Chrome o oferece para experimentação, com flag local e origin trial. A própria documentação recomenda tratá-lo como melhoria progressiva: sem suporte, a aplicação deve continuar funcionando normalmente.

Essa instabilidade foi a principal razão para manter a lógica de produto separada da camada de registro.

Hoje posso oferecer o mesmo contrato por WebMCP a um agente do navegador e por ClientTools ao chat incorporado. Amanhã o transporte pode mudar. A ação de selecionar um veículo, validar uma permissão ou preparar uma geofence não deveria precisar mudar junto.

A interface passa a ter uma API para intenções

APIs tradicionais conectam sistemas. Ferramentas de cliente conectam intenção e interface.

Isso abre espaço para um tipo diferente de produto com IA. O agente deixa de ser uma caixa de respostas e passa a colaborar dentro do fluxo que o usuário já conhece. Ele pode explicar, perguntar, agir e mostrar o resultado no mesmo lugar.

Para mim, essa é a promessa mais interessante de WebMCP e ClientTools. Não é eliminar a interface. É dar a ela uma segunda forma de uso.

Botões, formulários e mapas continuam importantes. Agora eles podem dividir o mesmo contrato com agentes que entendem objetivos em linguagem natural. Quando esse contrato é bem desenhado, onboarding vira orientação ativa, cadastro vira conversa estruturada e operações complexas deixam de depender de uma sequência frágil de cliques.