Cuando los agentes de IA usan mal su API, revise su documentación. El playbook AX de Microsoft muestra cómo

Imagine un equipo de plataforma interna que lanza la versión 3 de su SDK de acceso a datos. Un mes después, la mitad del código nuevo en toda la empresa sigue llamando al método de la versión 2 que quedó obsoleto. Nadie escribió ese código a mano. Lo hicieron los agentes de código, porque todo lo que podían leer, desde ejemplos antiguos hasta respuestas en foros y una página desactualizada en la documentación interna, los dirigía a la vieja manera.

La reacción habitual es culpar al modelo y esperar uno mejor. El equipo de relaciones con desarrolladores de Microsoft sugiere una reacción distinta: evaluar la experiencia del agente con su tecnología tal como alguna vez evaluó la de un desarrollador.

El 9 de octubre, Waldek Mastykarz, principal developer advocate en Microsoft, publicó el Agent Experience (AX) Practitioner Playbook, “nuestro método para evaluar qué hacen los agentes de código de IA con su tecnología”. Nació de evaluaciones de Azure, Azure Cosmos DB, SharePoint Framework y la extensibilidad de Microsoft 365 Copilot desde el otoño de 2025.

Encuentre dónde falló

La idea más útil del playbook es que “el agente se equivocó” no es un diagnóstico. Su análisis de trayectoria separa fallos que parecen idénticos en el código final: una extensión que nunca se cargó, una que se cargó pero nunca se llamó, y una que se llamó pero se aplicó incorrectamente. El playbook nombra nueve patrones de fallo recurrentes.

1. Existe la skill, la extensión o la documentación
2. El agente la carga
3. El agente la llama para la tarea
4. El agente la aplica correctamente
5. El código se ejecuta y cumple los criterios

Lo que usted publicaLo que muestra la trayectoria

Cada fallo tiene un responsable distinto. Si la extensión nunca se cargó, el problema es el empaquetado o el descubrimiento. Si se cargó pero no se llamó, su descripción no coincidía con cómo el agente enmarcó la tarea. Si se llamó y se aplicó mal, la documentación o el ejemplo están mal. Mejores modelos pueden reducir algunos de estos errores. Ninguno de ellos arregla un ejemplo desactualizado.

Corrija la fuente y demuestre la corrección

El método cierra el ciclo en la fuente. Las correcciones propuestas a docs, skills o descripciones de herramientas se prueban como hipótesis contra los mismos escenarios antes de publicarlas, y la evidencia va al equipo dueño del producto. Microsoft dice que este enfoque produjo 46 mejoras cerradas en el Azure Cosmos DB Agent Kit y docenas de correcciones implementadas en docs y extensiones de agente en general.

El modelo de evaluación es igual de deliberado. Los resultados necesitan criterios que juzguen el significado, además de gates que confirmen que el código realmente se ejecuta. Los criterios deben escribirse para que un juez los puntúe de manera consistente, calibrados y versionados a medida que el producto cambia. Ese último punto es fácil de omitir: un SDK que cambia mientras sus criterios de evaluación permanecen iguales pronto se calificará contra la respuesta equivocada. Es el principio que describimos en la IA regulada necesita pruebas desde fuera del modelo: un juez LLM cuenta como evidencia solo una vez que se ha calibrado.

Una skill complementaria, AX Practitioner, ayuda a las personas a aplicar el método. Microsoft informa que en 330 preguntas, sus respuestas promediaron un 95% de coincidencia con el playbook. Esa cifra mide la fidelidad al playbook, según lo informado por sus autores, no la precisión del agente de código.

Sus plataformas internas son el público real

Microsoft escribió esto para sus propios productos, pero el público más amplio está dentro de las empresas. Toda compañía con una plataforma de desarrollo interno, bibliotecas compartidas, golden paths y estándares de API ahora tiene un segundo tipo de consumidor: los agentes que usan sus desarrolladores. Esos agentes leen la wiki interna, los archivos README y los repositorios de ejemplo de manera más literal que cualquier persona, y repiten lo que encuentran a escala.

Eso convierte la experiencia del agente en una responsabilidad de ingeniería de plataforma con tres consecuencias prácticas:

• Alguien es responsable. Para cada SDK o API interno, nombre al equipo responsable de cómo lo usan los agentes, de la misma manera que alguien es dueño de su documentación para desarrolladores.
• Los escenarios se convierten en pruebas de regresión. Un pequeño conjunto de tareas realistas de agentes por plataforma, que se vuelven a ejecutar cuando la plataforma cambia, detecta regresiones en docs y ejemplos antes de que se propaguen por el código generado.
• Los ejemplos antiguos se retiran a propósito. Los patrones obsoletos en ejemplos y docs son ahora una fuente activa de defectos, porque los agentes los recuperan.

Hicimos un punto relacionado cuando Google convirtió su documentación para desarrolladores en una API para agentes: la documentación se está convirtiendo en contexto para agentes. El playbook de Microsoft añade la disciplina que debería acompañarla, midiendo si ese contexto funciona realmente. Y como lo que producen los agentes entra en la cadena de suministro de software, como describimos en la fábrica de software gobernada de GitLab, un defecto en sus docs puede convertirse en un defecto en el código de producción en cuestión de días.

El playbook es un método, no un producto, y sus resultados son de Microsoft. Sigue siendo la descripción pública más clara de un trabajo que la mayoría de los equipos de plataforma aún no ha notado que ahora tienen.