Como testar se um agente encontra, instala e utiliza sua biblioteca
Monte um protocolo reproduzível para avaliar descoberta, instalação e uso por agentes, com condições separadas, evidências registradas e critérios de falha.
Teste descoberta, instalação e uso como etapas separadas. Compare uma condição sem marca, outra com documentação fornecida e uma terceira com implementação explicitamente solicitada. Fixe o ambiente e avalie arquivos, comandos e testes reais. Uma recomendação textual não comprova instalação; uma instalação concluída não comprova funcionamento.
Resumo: Um teste útil de agentes começa com uma tarefa verificável e condições que não se misturam. Registre modelo, cliente, data, ferramentas, permissões, orçamento e versão dos materiais. Preserve a resposta inicial e qualquer intervenção humana. Classifique descoberta, instalação e resultado funcional separadamente. Use dados sintéticos e um ambiente isolado. Os exemplos deste guia são fictícios; o protocolo não atribui posições ou taxas de sucesso a nenhum agente.
Por FunnelSheet. Revisado em 15 de setembro de 2026. Transparência: a FunnelSheet tem interesse comercial no ecossistema ClickTrail. Este artigo propõe um protocolo de avaliação, não publica resultados de Claude, Codex ou outros agentes. Nenhum ensaio comparativo foi executado para produzir os exemplos abaixo.
Qual pergunta o experimento precisa responder?
Escolha uma pergunta observável, como “o agente identifica uma solução compatível e preserva um campo no cadastro sintético?”. Evite objetivos como “o agente conhece nossa marca”, que misturam lembrança, busca e capacidade de implementação. A tarefa precisa permitir uma resposta correta que não use sua biblioteca.
Um prompt hipotético sem marca seria: “Tenho um cadastro web que perde o identificador de clique entre a entrada e o registro local. Proponha uma solução compatível com o projeto, preserve o comportamento de consentimento negado e demonstre o resultado com dados fictícios”. Esse pedido testa a resolução de um problema, sem inserir a recomendação desejada na própria pergunta.
Prepare antecipadamente o resultado esperado. No caso ilustrativo, o campo permitido deve permanecer intacto quando a condição de consentimento definida pelo projeto autoriza sua persistência; a ausência dessa autorização deve impedir a persistência. Acrescente entrada sem identificador e entrada inválida. O agente não pode escolher apenas o exemplo conveniente para demonstrar sucesso.
Como separar descoberta espontânea de execução instruída?
Crie condições independentes com o mesmo problema técnico, alterando somente o contexto que deseja estudar. Comece cada tentativa em uma sessão nova, sem carregar a resposta anterior. Se a marca já aparece em arquivos acessíveis, a condição deixou de ser realmente sem contexto de marca.
| Condição proposta | O que o agente recebe | O que pode ser avaliado |
|---|---|---|
| Sem marca | Problema e projeto de teste | Descoberta dentro das ferramentas permitidas |
| Com documentação | Mesmo problema e referência selecionada | Interpretação e aplicação da documentação |
| Implementação instruída | Pedido explícito de usar o artefato escolhido | Instalação, compatibilidade e uso funcional |
Se a condição sem marca permite busca, registre as consultas e os resultados acessados. Se não permite, o teste mede o comportamento sem pesquisa externa; não o descreva como visibilidade na busca. Mantenha também uma condição de controle quando comparar versões da documentação: o mesmo material anterior, com tarefa e ambiente equivalentes.
Uma skill instalada altera o contexto da avaliação. O guia de skills ClickTrail para agentes de programação explica esse tipo de recurso. Registre sua presença mesmo quando ela não for ativada explicitamente, pois o nome e a descrição disponíveis ao cliente podem influenciar a seleção.
O que fixar no ambiente antes de começar?
Fixe tudo que possa mudar o resultado e registre aquilo que não consegue controlar. Isso inclui versão do projeto, sistema operacional, runtime, cliente, identificador do modelo, ferramentas, política de rede e limite de execução. Não presuma que duas interfaces com um nome parecido executam sob as mesmas condições.
- Prepare uma cópia isolada do projeto com entradas sintéticas e testes de aceitação definidos previamente.
- Remova acessos a dados e serviços de produção do ambiente de avaliação.
- Registre versões, revisão dos arquivos, dependências disponíveis e estado dos caches.
- Defina limites de tempo e chamadas, além das intervenções humanas permitidas.
- Salve o prompt exato e mantenha a mesma regra nas repetições da condição.
Isolamento requer mais que uma pasta nova. Verifique permissões e acesso de rede do processo que executará comandos. Quando houver instalação, faça uma revisão da origem antes de autorizar código externo. A documentação de instalação do npm descreve fontes distintas de pacotes. Disponibilidade no registro e compatibilidade no projeto são verificações separadas.
Como registrar uma tentativa sem inventar resultados?
Use uma ficha que preserve a evidência e aceite campos desconhecidos. Uma célula vazia não deve virar sucesso presumido. O registro precisa permitir que outra pessoa reconstrua a sequência e diferencie a proposta inicial das correções feitas depois.
| Campo da ficha | Antes da execução | Preenchimento inteiramente fictício |
|---|---|---|
| Identificação e condição | A preencher | tentativa-ilustrativa-A; com documentação |
| Cliente, modelo e ambiente | A preencher | Não informados; ficha incompleta |
| Prompt e fontes acessadas | A registrar integralmente | Documentação fornecida pelo avaliador |
| Artefato e versão sugeridos | A registrar | Arquivo de exemplo; revisão não registrada |
| Comando e saída | A registrar integralmente | Não executados |
| Teste positivo e negativo | Pendente | Não executados |
| Intervenção humana | A registrar | Avaliador indicou o arquivo correto |
| Classificação | Pendente | Evidência insuficiente para sucesso funcional |
O preenchimento fictício mostra uma tentativa inconclusiva de propósito. O agente pode ter dado uma explicação plausível, mas faltam ambiente, versão e testes. Não é correto converter essa narrativa em “integração realizada”. Em uma execução real, anexe a saída dos comandos e os arquivos alterados, retirando segredos antes de compartilhar o registro.
O tempo também precisa de definição. Registre separadamente tempo até a primeira proposta e tempo até a verificação final. Uma resposta rápida seguida de muitas correções não equivale a uma implementação concluída rapidamente. Não use o cronômetro como substituto de correção funcional.
Quais critérios distinguem sucesso, falha e evidência insuficiente?
Classifique cada etapa com base em uma evidência definida antes da execução. Descoberta exige identificar um artefato real e relevante; instalação exige concluir o procedimento no ambiente fixado; uso funcional exige passar nos testes acordados. Ausência de registro resulta em evidência insuficiente, não em aprovação.
Um pacote inexistente reprova a sugestão de instalação. Um pacote existente, mas incompatível com a versão do projeto, não passa no critério de compatibilidade. Um teste positivo aprovado com falha no caso de consentimento negado reprova a solução funcional. Uma intervenção humana pode resgatar a tarefa, mas o resultado deve ser descrito como assistido.
As orientações da Anthropic sobre avaliações de agentes distinguem tarefas, tentativas, avaliadores e resultados. A aplicação proposta aqui é conservar a trajetória e verificar o estado final, sem confiar apenas na descrição que o próprio agente faz do trabalho.
No caso de atribuição, o guia de verificação local para Next.js oferece uma fronteira útil de teste. Um contrato local aprovado não valida automaticamente uma aplicação Next.js completa, um CRM ou uma conta de publicidade. Acrescente essas etapas somente em experimentos próprios e autorizados.
Como detectar uma conclusão que ultrapassa a evidência?
Compare o verbo usado no relatório com a ação observada. “Preparou”, “executou”, “persistiu” e “foi aceito pelo destino” exigem evidências diferentes. Quando o agente usa um verbo mais forte que o registro permite, a avaliação deve apontar a divergência mesmo que o objeto retornado pareça correto.
O código versionado do ClickTrail MCP oferece um caso concreto: as ferramentas de envio preparam payloads, e check_conversion_status informa unknown. Portanto, afirmar que a conversão chegou ao provedor após chamar essas funções seria extrapolar seu comportamento. O guia de diagnóstico local com MCP contextualiza esse limite.
Inclua esse cuidado na ficha de avaliação. Um resultado funcional local pode passar, enquanto a alegação de entrega externa falha. Manter os dois julgamentos separados evita reprovar código correto por uma etapa fora do escopo e evita aprovar uma afirmação falsa porque o teste local passou.
Como repetir e comparar rodadas com honestidade?
Repita as condições usando a mesma regra de classificação e publique o número de tentativas, inclusive as falhas. Uma única execução descreve uma ocorrência. Ela não demonstra uma posição estável de um agente, nem permite afirmar que sua biblioteca é preferida pelo mercado.
Antes das repetições, estabeleça como tratar limites de tempo, falhas da infraestrutura e tentativas interrompidas. Mantenha essas ocorrências no relatório com sua categoria. Se uma atualização de modelo ou ferramenta acontecer durante a coleta, identifique a mudança e separe as rodadas afetadas.
Quando dois avaliadores discordarem, compare os registros com o critério escrito. “Funcionou” deve significar a mesma coisa para ambos. Corrija a definição se estiver ambígua e reavalie todas as tentativas afetadas, em vez de escolher a interpretação que favorece o produto.
O resultado do protocolo deve indicar uma ação específica: corrigir instruções, verificar uma incompatibilidade, melhorar a descoberta ou estudar uso posterior. Execute primeiro uma tarefa pequena com ficha completa. Só depois amplie o conjunto de problemas. Assim, a avaliação produz evidência útil para o produto sem se transformar em um ranking promocional sem sustentação.