Quando agentes de programação erram sua API, teste a documentação. O playbook AX da Microsoft mostra como

Imagine um time de plataforma interna que lança a versão 3 do seu SDK de acesso a dados. Um mês depois, metade do novo código em toda a empresa ainda chama o método da versão 2 que ele depreciou. Ninguém escreveu esse código à mão. Agentes de programação o fizeram, porque tudo que eles podiam ler, de exemplos antigos a respostas de fórum a uma página desatualizada na documentação interna, apontava para o jeito antigo.

A reação comum é culpar o modelo e esperar por um melhor. O time de relações com desenvolvedores da Microsoft sugere uma reação diferente: avaliar a experiência do agente com sua tecnologia da mesma forma que você um dia avaliou a de um desenvolvedor.

Em 9 de outubro, Waldek Mastykarz, principal developer advocate na Microsoft, publicou o Agent Experience (AX) Practitioner Playbook, “nosso método para avaliar o que agentes de IA de programação fazem com sua tecnologia.” Ele surgiu de avaliações do Azure, do Azure Cosmos DB, do SharePoint Framework e da extensibilidade do Microsoft 365 Copilot desde o outono de 2025.

Descubra onde quebrou

A ideia mais útil do playbook é que “o agente errou” não é um diagnóstico. Sua análise de trajetória separa falhas que parecem idênticas no código final: uma extensão que nunca carregou, uma que carregou mas nunca foi chamada, e uma que foi chamada mas aplicada incorretamente. O playbook nomeia nove padrões de falha recorrentes.

1. Skill, extensão ou doc existe
2. O agente carrega
3. O agente chama para a tarefa
4. O agente aplica corretamente
5. O código roda e atende aos critérios

O que você publicaO que a trajetória mostra

Cada falha tem um dono diferente. Se a extensão nunca carregou, o problema é empacotamento ou descoberta. Se carregou mas não foi chamada, sua descrição não correspondia a como o agente enquadrou a tarefa. Se foi chamada e mal aplicada, a documentação ou o exemplo está errado. Modelos melhores podem reduzir alguns desses erros. Nenhum deles corrige um exemplo desatualizado.

Corrija a fonte, e prove a correção

O método fecha o loop na fonte. Correções propostas para docs, skills ou descrições de ferramentas são testadas como hipóteses contra os mesmos cenários antes do envio, e a evidência vai para o time que é dono do produto. A Microsoft diz que essa abordagem produziu 46 melhorias fechadas no Azure Cosmos DB Agent Kit e dezenas de correções enviadas para docs e extensões de agente no geral.

O modelo de avaliação é igualmente deliberado. Resultados precisam de critérios que julguem significado, além de gates que confirmem que o código realmente roda. Critérios devem ser escritos para que um juiz os pontue de forma consistente, calibrados, e versionados conforme o produto muda. Esse último ponto é fácil de pular: um SDK que muda enquanto seus critérios de avaliação permanecem os mesmos logo será avaliado contra a resposta errada. É o princípio que descrevemos em IA regulada precisa de prova de fora do modelo: um juiz LLM conta como evidência só depois de ter sido calibrado.

Uma skill companheira AX Practitioner ajuda as pessoas a aplicar o método. A Microsoft relata que, em 330 perguntas, suas respostas tiveram uma média de 95% de concordância com o playbook. Esse número mede fidelidade ao playbook, conforme relatado por seus autores, não a precisão do agente de programação.

Suas plataformas internas são o público real

A Microsoft escreveu isso para seus próprios produtos, mas o público maior está dentro das empresas. Toda empresa com uma plataforma interna de desenvolvedor, bibliotecas compartilhadas, golden paths e padrões de API agora tem um segundo tipo de consumidor: os agentes que seus desenvolvedores usam. Esses agentes leem o wiki interno, os arquivos README e os repositórios de exemplo de forma mais literal do que qualquer pessoa, e repetem o que encontram em escala.

Isso torna a experiência do agente uma responsabilidade de engenharia de plataforma com três consequências práticas:

• Alguém é dono disso. Para cada SDK ou API interna, nomeie o time responsável por como os agentes o usam, da mesma forma que alguém é dono de sua documentação de desenvolvedor.
• Cenários se tornam testes de regressão. Um pequeno conjunto de tarefas realistas de agente por plataforma, reexecutado quando a plataforma muda, captura regressões em docs e exemplos antes que se espalhem pelo código gerado.
• Exemplos antigos são aposentados de propósito. Padrões depreciados em exemplos e docs são agora uma fonte ativa de defeitos, porque os agentes os recuperam.

Fizemos um ponto relacionado quando o Google transformou sua documentação de desenvolvedor em uma API para agentes: a documentação está se tornando contexto do agente. O playbook da Microsoft adiciona a disciplina que deveria vir com isso, medindo se esse contexto realmente funciona. E porque o que os agentes produzem entra na cadeia de suprimentos de software, como descrevemos em a fábrica de software governada do GitLab, um defeito na sua documentação pode se tornar um defeito no código de produção em dias.

O playbook é um método, não um produto, e seus resultados são da própria Microsoft. Ainda é a descrição pública mais clara de um trabalho que a maioria dos times de plataforma não percebeu que agora tem.