Avaliações para WebMCP

Kasper Kulikowski

Publicado em: 19 de maio de 2026

O WebMCP oferece suporte a agentes que usam modelos de IA generativa. Para testar qualquer sistema usando IA generativa, seus testes precisam oferecer suporte a resultados probabilísticos: uma entrada pode levar a milhares de respostas com diferentes graus de precisão. Essa técnica de teste é chamada de avaliações ou evals.

Antes de lançar ferramentas na produção, confirme se os agentes entendem quando chamar a ferramenta, como executá-la e quais respostas são aceitáveis. Abordar oportunidades de falha antes que elas aconteçam.

Escreva avaliações para testar os pontos de contato do seu sistema com um modelo de linguagem grande (LLM):

• Verifique se o modelo entende a finalidade da ferramenta com base na descrição e no esquema.
• Verifique se o modelo escolhe a ferramenta certa com os parâmetros corretos para atender à intenção do usuário.
• Confirme se o modelo está agindo com base nas informações recebidas, por exemplo, para usar informações e chamar outra ferramenta.
• Verifique se as jornadas dos usuários foram bem-sucedidas. Considerando a intenção do usuário, um agente pode concluir com sucesso a jornada do usuário no meu site com as ferramentas fornecidas?

Continue escrevendo testes determinísticos clássicos para qualquer interação do sistema que não se comunique com o modelo.

Modos de falha

Os desenvolvedores precisam testar os sistemas para evitar falhas antes que elas aconteçam. Para isso, é necessário entender quando o sistema pode falhar, tanto por conta própria quanto ao interagir com fatores externos. No WebMCP, a ferramenta em si pode falhar, e os agentes podem não conseguir usá-la como esperado.

As ferramentas do WebMCP podem falhar, e o agente também pode falhar com elas. Por exemplo, digamos que o usuário queira adicionar uma camiseta ao carrinho.

Falha	Exemplo	Resolver problemas
O agente não seleciona a ferramenta correta ou chama diretamente a ferramenta errada.	O agente pula addToCart e vai direto para checkout.	A description da ferramenta é clara, completa e reflete com precisão o que ela faz? O functionName é intuitivo e descritivo? A ferramenta está exposta corretamente ao LLM no estado/contexto atual? O esquema dessa ferramenta é muito parecido com o de outra, o que causa ambiguidade nas chamadas?
o agente chama as ferramentas na ordem errada	O agente chama checkout e depois addToCart.	As descrições das ferramentas se sobrepõem, confundindo o LLM sobre a sequência necessária? A saída de uma ferramenta anterior fornece o contexto necessário para a próxima chamada de ferramenta? O estado é atualizado corretamente e as novas ferramentas são expostas ao LLM conforme o esperado? O caso de uso de ponta a ponta ainda está correto se determinadas ferramentas forem chamadas em uma ordem diferente? Você testou a cadeia de chamadas de ferramenta específica isoladamente, forçando as chamadas anteriores para confirmar se o LLM escolhe a próxima etapa correta?
O agente chama a ferramenta com argumentos incorretos	O agente chama addToCart, mas adiciona sapatos em vez de uma camiseta.	O inputSchema está claramente definido, incluindo valores de enum e um bom description para cada propriedade? Todos os parâmetros obrigatórios estão marcados e verificados explicitamente? A descrição do argumento orienta explicitamente o LLM sobre como mapear a entrada do usuário para os dados estruturados esperados (como um ID ou formato específico)?

E se o usuário quiser verificar o que tem no carrinho?

Falha	Exemplo	Resolver problemas
A saída da ferramenta está incorreta ou ela não encontra algo.	O usuário pede para viewCart, mas o agente informa o custo total do carrinho, em vez dos nomes dos produtos e preços individuais.	A lógica da ferramenta tem bugs (verifique com testes determinísticos)? O estado da interface foi atualizado corretamente? O agente recebeu as informações certas sobre o efeito colateral? Se a saída for usada pelo LLM para chamadas subsequentes, ela será formatada claramente para ingestão pelo LLM? A saída é muito detalhada? Ele contém apenas as informações essenciais mínimas que o LLM precisa para a próxima ação?

Por fim, uma ferramenta pode falhar de qualquer maneira que o JavaScript falhe. Para resolver o problema, investigue o seguinte:

• O código da ferramenta processa corretamente todos os possíveis erros e exceções de tempo de execução?
• O erro é informado ao agente e ao modelo de forma adequada?
• As APIs ou serviços externos de que a ferramenta depende estão funcionando corretamente?
• A estrutura de erro está clara o suficiente para que o modelo possa diferenciar entre um problema temporário (nova tentativa) e uma falha crítica?

Testar ferramentas de forma isolada

Se um agente não conseguir descobrir qual ferramenta chamar para uma solicitação como "Quero uma pizza pequena", ele não terá chance em uma jornada complexa do usuário.

Ao testar ferramentas isoladamente, você pode otimizar seus esquemas e descrições antes de executar uma simulação de navegador.

DICA: você pode acionar uma chamada de ferramenta do WebMCP using navigator.modelContext.executeTool(...).

Medir a acurácia das chamadas

Confira nossa demonstração, o WebMCP zaMaker. Quando o usuário diz: "Quero uma pizza pequena", você pode esperar uma resposta do modelo indicando a intenção de fazer uma chamada set_pizza_size com o argumento "size":"Small".

A função expectedCall define a função e o argumento esperados. Essa abordagem confirma que o agente vai escolher a ferramenta correta para atender à intenção do usuário, com base no esquema fornecido.

{
  "messages": [
    {
      "role": "user",
      "content": "I'd like a small pizza."
    }
  ],
  "expectedCall": [
    {
      "functionName": "set_pizza_size",
      "arguments": { "size": "Small" }
    }
  ]
}

O expectedCall é usado para realizar um teste determinístico baseado em regras:

É possível vincular suas ferramentas do WebMCP ao ciclo de vida de um componente, o que significa que você precisa testar quando o estado do aplicativo corresponde ao que o WebMCP espera. Para gerenciar isso, forneça uma lista completa de ferramentas relevantes para o estado que você quer avaliar. Por exemplo, um usuário está navegando em conjunto com o agente e abre o WebMCP zaMaker.

[
...
  {
    "name": "add_topping",
    "description": "Add one or more toppings to the pizza",
    ...
  },
  {
    "name": "set_pizza_size",
    "description": "Set the pizza size directly.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "size": {
          "type": "string",
          "enum": [
            "Small",
            "Medium",
            "Large",
            "Extra Large"
          ],
          "description": "The specific size name."
        },
      }
    }
  },
  {
    "name": "set_pizza_style",
    "description": "Set the style of the pizza (colors/theme)",
  ...
  },
...
]

...
 "expectedCall": [
   {
     "functionName": "set_pizza_size",
     "arguments": { "size": "Small" }
   }
 ]
...

Ao abrir, o WebMCP expõe as ferramentas add_topping, set_pizza_size e set_pizza_style. Para testar com precisão qualquer uma dessas ferramentas individuais, inclua todas elas para criar um estado simulado e completo.

OBSERVAÇÃO: um agente pode ter acesso a outras ferramentas, mas o melhor que você pode fazer é avaliar as ferramentas que você fornece.

Agora que você sabe que o agente chama a ferramenta certa conforme necessário, teste se a chamada de ferramenta tem os parâmetros corretos e se o resultado é o esperado. Há duas etapas: testes determinísticos e testes probabilísticos.

Executar testes determinísticos

Como as ferramentas do WebMCP são criadas com JavaScript ou como anotações HTML, é possível escrever testes determinísticos para realizar as seguintes tarefas:

• Verifique a lógica da ferramenta.
• Confirme se as dependências foram chamadas corretamente.
• Confirme se a interface do usuário foi atualizada conforme o esperado, além de outros efeitos colaterais intencionais.
• Verifique se as informações retornadas correspondem ao valor esperado.
• Valide os parâmetros de teste.

Por exemplo, se a ferramenta usar uma função SearchComponent, teste transmitindo uma simulação de SearchComponent. Simule o ambiente em que a ferramenta está operando para ter os melhores resultados possíveis. Essa é a mesma técnica que você usaria para escrever outro teste de integração de aplicativo.

Executar testes probabilísticos

Se você precisar de uma saída do modelo para chamar as próximas ferramentas corretamente, escreva avaliações.

É possível que os usuários façam consultas diretas ao modelo perguntando especificamente o que a ferramenta faz ou uma consulta ambígua que implica o uso de uma ferramenta. Por exemplo, "Adicione pepperoni à minha pizza" é uma consulta direta. "Quero todas as carnes na minha pizza" é mais ambíguo e exige que o modelo entenda que precisa da ferramenta add_topping e quais coberturas podem ser definidas como carne.

Ao criar conjuntos de dados para suas avaliações, inclua consultas diretas que testam a execução da ferramenta de comparação e consultas abertas que testam o raciocínio do modelo e a lógica de seleção de ferramentas.

Se você tem uma cafeteria, pode ajudar os usuários que pedem ao agente para recomprar o mesmo café que pediram no mês passado. Escreva uma ferramenta para pesquisar pedidos anteriores, OrderHistoryService, e outra para pedir o café. Para testar o serviço de histórico de pedidos, você pode enviar um simulacro que retorne um ID de produto de café.

Neste exemplo, você avalia se o modelo entende a intenção da consulta, escolhe a ferramenta certa e se ela fornece as informações adequadas para realizar uma ação. Se o modelo não chamar get_order_history, ele não saberá qual item_id usar para order_product.

Testes de ponta a ponta

Escreva testes de ponta a ponta para garantir que os usuários e os agentes deles possam concluir as jornadas com sucesso. Além de testar as ferramentas individuais, você também testa se as ações de várias etapas são realizadas na ordem correta.

Por exemplo, você tem uma loja de roupas on-line. Um usuário pergunta ao agente: "Quero comprar uma jaqueta preta e um par de jeans. Você pode fornecer um detalhamento dos materiais usados?"

Uma jornada de agente bem-sucedida pode ser assim:

1. Navegue até a categoria de roupas.
2. Encontre uma das peças de roupa solicitadas (a ordem não é importante).
3. Encontrar um item específico (search_clothes).
4. Receba os detalhes do produto que contêm a lista de materiais (get_product_details).
5. Repita as etapas de 2 a 4 para cada item solicitado.

Quando o agente chega à etapa 2, ele pode pesquisar primeiro a camiseta preta ou o jeans. A ordem não importa. No entanto, as demais etapas precisam ser seguidas em sequência.

Escreva uma avaliação de ponta a ponta para verificar se o agente chama as ferramentas na ordem esperada:

{
  "messages": [
    {
      "role": "user",
      "content": "I am looking to buy a black jacket and a pair of jeans.
        Could you provide a breakdown of the materials used ?"
    }
  ],
  "expectedCall": [
    {
      "functionName": "navigate_to_category",
      "arguments": { "category": "clothes" }
    },
    {
      "unordered": [
        {
          "ordered": [
            {
              "functionName": "search_clothes",
              "arguments": { "query": "black jacket" }
            },
            {
              "functionName": "get_product_details",
              "arguments": { "productId": "JACKET002" }
            }
          ]
        },
        {
          "ordered": [
            {
              "functionName": "search_clothes",
              "arguments": { "query": "jeans" }
            },
            {
              "functionName": "get_product_details",
              "arguments": { "productId": "JEANS001" }
            }
          ]
        }
      ]
    }
  ]
}

Avaliar falhas no meio da cadeia

Às vezes, um agente precisa chamar várias ferramentas em sequência. O que acontece se uma ferramenta falhar no meio desse processo? Por exemplo, um usuário quer pedir uma pizza com um código de cupom:

"Quero uma pizza pequena de pesto. Use meu código promocional, FreePizza"

É possível que o agente falhe na add_discount_coupon e prossiga para o pagamento de uma pizza com preço integral. Para testar a ferramenta add_discount_coupon, você pode executar manualmente essa sequência de chamadas de ferramentas, sem interagir com um modelo, para simular esse cenário. Coloque o aplicativo no estado em que você prevê que a ferramenta vai falhar. Nesse caso, é depois da ferramenta start_checkout. Em seguida, avalie o add_discount_coupon isoladamente.

Teste o WebMCP

Comece a testar as avaliações para ferramentas isoladas e avalie seus próprios sites ativados com o WebMCP usando qualquer agente compatível com o WebMCP:

• Faça o download das nossas ferramentas de avaliação experimental no GitHub (link em inglês).
• Confira nosso curso Criar avaliações de IA.