Agent experience: como avaliar agentes de código
Agent experience é a experiência que um agente de IA de código tem ao descobrir, escolher e usar a sua tecnologia. Neste artigo, você vai entender como avaliar, diagnosticar e melhorar essa experiência com o método do AX Practitioner Playbook, publicado pela Microsoft em outubro de 2026.
O que é agent experience
Hoje, boa parte do código não nasce mais das mãos do desenvolvedor. Ele descreve o que quer em um prompt, e o agente decide qual SDK usar, qual versão instalar e qual padrão de autenticação seguir.
Por isso, quem cria uma tecnologia ganhou uma nova audiência. Além das pessoas que leem a documentação, existem agentes que consomem docs, ferramentas MCP, skills, plugins, instruções, CLIs e APIs.
O termo agent experience, ou simplesmente AX, foi cunhado por Mathias Biilmann, da Netlify, em janeiro de 2025. Na prática, ele descreve o quão perto do uso correto um agente chega quando trabalha com o seu produto.
Faça um teste simples: peça a um agente para criar uma aplicação com a tecnologia que você conhece bem. O código provavelmente vai compilar, mas um olhar atento costuma revelar uma versão errada do SDK, um padrão de autenticação obsoleto ou uma decisão de arquitetura que o time do produto nunca recomendaria.
Por que modelos novos não resolvem o problema
Muita gente acredita que basta esperar a próxima geração de modelos. No entanto, a data de corte de conhecimento indica apenas o limite máximo dos dados, não o quanto o modelo conhece o seu produto.
O time de DevRel da Microsoft relata ter visto um modelo mais novo saber menos sobre uma tecnologia do que o seu antecessor. Ou seja, esperar não é estratégia, porque os desenvolvedores usam a sua tecnologia hoje.
Em vez disso, corrigir as fontes que os agentes consultam melhora a agent experience agora. Além disso, essa correção entrega informação melhor para os modelos futuros.
O modelo de avaliação de agent experience
Benchmarks como o SWE-bench comparam modelos entre si, mas não dizem se um agente usa a sua tecnologia corretamente. Para isso, você precisa do seu conhecimento de domínio, porque só você sabe qual versão e qual padrão o time recomenda.
Uma avaliação de agent experience responde a uma pergunta mais útil. Dada a sua tecnologia, o agente a utiliza do jeito que deveria?
Os quatro pilares da avaliação
Toda avaliação nasce de quatro elementos, e cada um precisa atingir um padrão mínimo de qualidade:
- Cenários são os prompts que o desenvolvedor digita, executados sobre um workspace vazio ou já populado.
- Critérios são as verificações que decidem se o agente fez as escolhas certas.
- Perfis são os ambientes de execução, com sistema operacional, harness, modelo e extensões.
- Gates são as checagens mecânicas que confirmam que o código gerado funciona.
Os gates rodam em cascata, porque cada um só executa se o anterior passou. Primeiro vem o gate de pré-requisito, que verifica se o agente escolheu a tecnologia certa.
Por exemplo, se você pediu Cosmos DB e o agente construiu tudo em MongoDB, nada mais merece ser medido. Em seguida vêm build, testes, execução e, quando faz parte da tarefa, deploy.
Baseline, lift, drag e custo
Uma nota isolada diz muito pouco. Por isso, todo resultado precisa de uma comparação com um baseline, que é o mesmo cenário e o mesmo perfil, porém sem nenhuma extensão.
Quando a extensão melhora o resultado, você tem lift. Quando piora, você tem drag.
A conta é propositalmente simples: taxa de aprovação com a extensão menos a taxa de aprovação do baseline. Assim, qualquer dono de produto entende o número sem precisar de um cientista de dados.
Também não confunda uso com sucesso, porque o agente chamar a sua ferramenta não significa que ela ajudou. Além disso, meça o custo junto com a qualidade, já que um ganho que triplica o preço exige uma decisão consciente.
Além disso, modelos de linguagem não são determinísticos. Então, rode cada combinação de cenário e perfil pelo menos cinco vezes, porque uma única execução pode ser um ponto fora da curva.
Como desenhar cenários realistas
Um cenário é a pergunta que você faz sobre a sua tecnologia. Portanto, a qualidade do que você aprende depende diretamente da qualidade dessa pergunta.
O cenário contém apenas o prompt que um desenvolvedor real digitaria. Nada de instruções de avaliação, rubricas ou dicas sobre a resposta certa.
Se os desenvolvedores escrevem prompts vagos, é exatamente isso que você deve testar. Criar prompts artificialmente perfeitos afasta a avaliação da realidade.
Propensão e eficácia em agent experience
Existem dois tipos de pergunta que você pode fazer. A propensão mede se o agente descobre e escolhe a sua tecnologia sem que ela seja citada no prompt.
Por exemplo, o prompt pode pedir uma API que guarde dados de clientes em um banco de documentos. Se o agente escolher MongoDB em vez de Cosmos DB, você tem um achado de propensão.
Já a eficácia mede se o agente usa a tecnologia corretamente quando ela foi escolhida. Nesse caso, o prompt cita o produto e você testa se o agente conhece os padrões certos.
Para produtos novos, a propensão costuma ser o ponto de partida da agent experience. Por outro lado, tecnologias maduras geralmente revelam mais valor nos testes de eficácia.
Como escrever critérios de avaliação
Os critérios transformam o seu conhecimento de domínio em uma medida objetiva de agent experience. De fato, essa é a parte mais difícil do processo.
Um juiz baseado em LLM lê os artefatos gerados e decide se cada critério passa, falha ou deve ser ignorado. Já o comportamento de build e execução fica com os gates mecânicos.
Cada critério precisa de quatro partes: o que você verifica, o que passa, o que falha e quando ignorar. Veja um exemplo de critério bem escrito para um cenário com Cosmos DB:
# Critério para validar a versão do SDK do Cosmos DB
id: cosmos-sdk-version
check: Uses @azure/cosmos v4.x
pass: package.json specifies a stable version from 4.0.0 up to, but not including, 5.0.0
fail: Specifies an earlier major version, a prerelease version, or the deprecated documentdb package
skip: The application does not use Cosmos DB
Repare que o texto nomeia o pacote, a faixa de versões aceitas e os padrões errados. Dessa forma, o juiz não precisa adivinhar nada.
Evite também algumas armadilhas comuns:
- Deixar um LLM escrever os critérios do zero, porque ele carrega padrões antigos dos dados de treino.
- Testar estilo em vez de correção, com frases como "segue boas práticas".
- Penalizar o agente por algo que ele não controla, como as ferramentas que o harness carrega.
- Juntar várias preocupações em um único critério.
- Usar palavras vagas como correto, adequado ou atual.
Calibração e versionamento dos critérios
Antes de usar os critérios em produção, rode um ciclo de calibração. Primeiro, teste cada critério contra um artefato que deveria passar e outro que deveria falhar.
Depois, avalie os mesmos artefatos várias vezes para ver se o juiz chega sempre ao mesmo veredito. Por fim, peça para alguém que conhece o produto confirmar a precisão técnica.
Quando o conjunto estiver estável, trave uma versão. Assim, se uma nota surpreender, você investiga a saída e a trajetória antes de mudar o critério.
Perfis de agente para medir agent experience
Um perfil combina sistema operacional, harness, modelo, configurações de raciocínio e extensões, sempre com as respectivas versões. Exemplos de harness são o GitHub Copilot no Visual Studio Code, o Cursor e o Claude Code.
Para medir a agent experience, comece sempre por um perfil sem extensões. Ele mostra o que o agente sabe da sua tecnologia apenas com os dados de treino e as ferramentas nativas do harness.
Em seguida, adicione uma extensão por vez. Desse modo, você descobre se cada skill, servidor MCP ou arquivo de instruções gera lift ou drag de forma isolada.
Só depois teste combinações. O playbook mostra que extensões boas sozinhas podem piorar quando rodam juntas, seja por conflito de nomes de ferramentas ou por excesso de contexto.
Também escolha o ambiente que representa a maior parte do seu público. Afinal, rodar uma CLI no Linux porque é fácil de automatizar, quando seus desenvolvedores usam uma IDE no Windows, gera um número preciso sobre uma situação que ninguém vive.
Executando a avaliação e lendo o readout
A metodologia não depende de uma ferramenta específica. Contudo, o time de DevRel da Microsoft publicou o Scope, um sistema de avaliação open source que implementa o método do playbook.
Depois das execuções, os dados de agent experience viram um readout. Ele combina o gate de pré-requisito, os gates de execução, o resultado de cada critério, a comparação entre perfis e o custo de cada tarefa.
Ao ler o readout, procure primeiro estes sinais:
- Extensões carregadas que o agente nunca chamou.
- Casos em que o baseline supera um perfil com extensão, o que indica drag ativo.
- Critérios que falham em todas as execuções e em todos os perfis.
- Critérios inconsistentes, como 2 de 5 ou 3 de 5, em que o agente está à beira da decisão certa.
- Diferenças grandes de custo entre perfis com resultados parecidos.
Investigando trajetórias de agent experience
O readout diz o que falhou. Já a trajetória, que registra cada chamada de ferramenta, cada arquivo lido e cada decisão, mostra por que falhou.
O formato ATIF, sigla para Agent Trajectory Interchange Format, permite guardar e comparar essas trajetórias entre agentes diferentes. Além disso, quando o modelo expõe o raciocínio, você consegue ver o que ele considerou e o que descartou.
Descoberta, invocação e aplicação
Toda falha acontece em um de três estágios. Na falha de descoberta, a extensão nem chega ao contexto, porque o servidor MCP não iniciou ou a skill excedeu um limite de tamanho.
Na falta de invocação, a extensão carrega, mas o agente decide não usá-la. Geralmente a descrição da ferramenta não combina com a intenção do usuário ou o modelo confia demais no que já sabe.
Na falha de aplicação, o agente usa a tecnologia, porém de forma errada. Nesse caso, a correção está no conteúdo das docs, da skill ou das respostas da ferramenta.
Por fim, identifique a origem do problema: documentação, extensão, dados de treino ou o próprio agente. Uma falha de documentação pede uma correção na documentação, não uma nova skill por cima.
Padrões de falha mais comuns em agent experience
Depois de centenas de sessões, o time da Microsoft identificou padrões que se repetem em praticamente todas as tecnologias. Conhecê-los acelera o diagnóstico da agent experience do seu produto.
O agente ignora a sua extensão e usa os dados de treino. Normalmente o problema é vocabulário, porque a ferramenta fala em gerenciar operações de banco e o desenvolvedor pediu para construir uma API.
O agente segue as docs ao pé da letra. Se um exemplo traz uma versão fixa, ele instala aquela versão mesmo quando o desenvolvedor pediu a mais recente.
O agente já tem um plano antes de ler o seu conteúdo. Nesse caso, uma dica gentil não muda nada, mas um aviso que invalida o caminho errado muda.
Outros padrões aparecem com frequência. Por exemplo, ferramentas com vocabulário parecido confundem o agente, e extensões demais consomem contexto até deixar o resultado pior que o baseline.
Também é comum o agente editar arquivos manualmente em vez de rodar a sua CLI, porque edição de arquivos é a sua modalidade principal. Além disso, ele pode trocar um conhecimento correto por um conteúdo recuperado que enfatiza o padrão errado.
Seja qual for o padrão, mude uma superfície por vez e rode a mesma avaliação de novo. Caso contrário, você não saberá qual mudança causou o resultado.
Transformando achados em melhorias de agent experience
Uma avaliação só gera impacto quando alguém muda a fonte do comportamento. Então, o objetivo é sempre corrigir a origem, verificar o resultado e evitar novas camadas quando a origem pode mudar.
Trate cada mudança como uma hipótese. O time da Microsoft usou o Dev Proxy, um simulador de APIs, para interceptar as requisições do agente ao Microsoft Learn e devolver páginas modificadas antes de publicar qualquer alteração.
Com o plugin de respostas simuladas do Dev Proxy, um arquivo de mocks pode trocar uma página real por uma versão alterada:
{
"mocks": [
{
"request": {
"url": "https://learn.microsoft.com/sharepoint/dev/spfx/release-1.22.0*"
},
"response": {
"statusCode": 200,
"body": "@release-1.22.0-modified.md"
}
}
]
}
Dessa forma, você mede o efeito da mudança antes de abrir um pull request. Segundo o playbook, várias hipóteses do time estavam erradas e teriam piorado a experiência se fossem publicadas sem teste.
Quando você não é dono da superfície, leve as evidências ao time responsável. Comece mostrando o baseline, porque ver como um agente realmente aborda o produto revela pontos cegos de quem trabalha nele todos os dias.
Além disso, a agent experience muda mesmo quando o seu produto não muda. Por isso, repita a avaliação periodicamente com a mesma definição travada, para que os resultados continuem comparáveis.
O caso SPFx na prática
O apêndice do playbook mostra um ciclo completo com o SharePoint Framework, o SPFx. O cenário era um prompt mínimo pedindo para atualizar um projeto da versão 1.21.1 para a 1.22.2.
Para isso, o ambiente reproduzia o setup típico de quem usa SPFx: Windows 11, Visual Studio Code, GitHub Copilot Chat e o modelo Claude Sonnet 4.6. Os critérios foram agrupados em pré-requisito, dependências, configuração e uso idiomático.
Todas as execuções compilaram e rodaram. No entanto, a configuração correta passou em apenas 30 de 80 verificações no baseline.
A investigação revelou três causas. O agente lia a página release-1.22 e achava que ela cobria a 1.22.2, o guia de migração fixava a versão 1.22.1 nos comandos e uma dica sobre a CLI for Microsoft 365 era ignorada em todas as execuções.
Então, o time renomeou as páginas de release para usar a versão completa, trocou a dica por um aviso de que editar o package.json manualmente causa falhas de build e reescreveu o guia de migração como uma página conceitual. Depois disso, todas as execuções sem extensão passaram a usar a CLI por conta própria.
Na nova rodada, em setembro de 2026, a configuração correta chegou a 83 de 85.
O detalhe mais importante é que nenhuma dessas melhorias exigiu uma nova extensão. Foram duas mudanças na documentação e uma correção no harness, o que beneficia todos os desenvolvedores sem que eles instalem nada.
Conclusão sobre agent experience
Agentes de código já tomam decisões técnicas em nome de milhares de desenvolvedores. Portanto, cuidar da agent experience virou parte do trabalho de quem cria SDKs, APIs, CLIs, documentação ou extensões.
O método é direto: cenários realistas, critérios precisos, perfis representativos, gates mecânicos, baseline e várias execuções. Em seguida, você lê as trajetórias, encontra a causa e corrige a fonte.
Se você quer praticar esse raciocínio de especificar antes de gerar código, o Workshop Spec Driven Development do balta.io é um bom próximo passo. Para se aprofundar no método, baixe o playbook completo pelo anúncio oficial da Microsoft.
FAQ
O que é agent experience?
Agent experience é a experiência que agentes de IA têm ao descobrir, escolher e usar uma tecnologia. Na prática, mede o quão perto do uso correto o agente chega.
Qual a diferença entre agent experience e developer experience?
A developer experience foca na pessoa que lê a documentação e escreve o código. Já a agent experience foca no agente que consome docs, ferramentas e extensões para tomar decisões em nome dessa pessoa.
Quantas vezes devo rodar cada cenário?
O playbook recomenda pelo menos cinco execuções por combinação de cenário e perfil. Se os resultados ficarem divididos, aumente o número de execuções.
Preciso do Scope para aplicar o método?
Não, porque o método funciona com qualquer sistema de avaliação. O Scope apenas implementa o playbook em uma ferramenta open source pronta para uso.
Quando faz sentido criar uma nova skill?
Somente quando a origem do problema não pode ser corrigida rapidamente. Mesmo assim, a skill deve ser tratada como uma ponte temporária, com condição clara para ser aposentada.