Crear un agente de IA que investiga con herramientas y probar que no adivina

## Separar el motor de investigación de los plugins de cada servicio Organiza el sistema en capas explícitas: puntos de entrada para los usuarios, carga de configuración, un motor de investigación, un gestor de herramientas y fuentes, conjuntos de herramientas, instrucciones y destinos conectables. Los puntos de entrada deben dirigir las solicitudes y establecer el registro; la configuración debe validar los ajustes y construir las integraciones; el motor debe seleccionar herramientas, recopilar pruebas, analizar resultados y, de forma opcional, devolver los hallazgos a un destino autorizado. Mantén el comportamiento específico de cada proveedor tras complementos para que el bucle central pueda razonar sobre un contrato de herramientas estable. Carga las integraciones dinámicamente desde una configuración validada y mantén separadas la ingesta de fuentes, la investigación y las escrituras en destinos para que un diagnóstico de solo lectura no se convierta silenciosamente en una modificación externa. ## Hacer de cada herramienta un envoltorio delgado que explique con exactitud sus fallos Prefiere una envoltura ligera para un único punto de conexión u operación externos. Proporciona a cada integración un pequeño objeto de configuración validado, un requisito previo o comprobación de estado explícitos y una función de herramienta cuyos parámetros correspondan directamente a la solicitud subyacente. Evita las abstracciones pesadas de cliente cuando una llamada de transporte transparente facilite la inspección del comportamiento y los errores. Devuelve suficiente contexto del fallo para que quien realiza la llamada pueda corregirse: la consulta o el comando exactos, el intervalo temporal, los filtros, los parámetros pertinentes, el estado de la respuesta y el mensaje de error subyacente. Un resultado sin datos debe indicar qué se buscó y dónde. Conserva los controles de acceso, valida los comandos ejecutables, mantén las herramientas en modo de solo lectura de forma predeterminada y nunca expongas ni registres secretos en el control de versiones. ## Limitar cuántos datos devuelve una herramienta antes de que la IA los lea Nunca expongas una colección sin límites mediante una herramienta. Exige filtros en el servidor para los puntos de conexión que puedan devolver grandes conjuntos de resultados y diseña el esquema de modo que quienes realizan las llamadas no puedan omitir el parámetro de alcance más importante. Un desbordamiento de tokens o memoria provocado por una operación de listado sin restricciones es un defecto del contrato de la herramienta, no un problema de las instrucciones. Cuando el servicio remoto no pueda filtrar adecuadamente, añade controles explícitos en el cliente, como profundidad máxima, límites de resultados, selección de campos o una expresión de consulta estructurada. Informa de los truncamientos y los límites aplicados. Mantén compacta la respuesta predeterminada, pero permite ampliaciones específicas cuando la investigación necesite más pruebas. ## Mantener funcionando los nombres viejos de configuración y poner lo común en el nivel de clase correcto Al cambiar el nombre de un campo de configuración, acepta los nombres obsoletos como entrada adicional, asígnalos al campo actual y emite una advertencia de obsolescencia. Conserva únicamente los nombres actuales en el esquema público y la salida serializada para que la compatibilidad no contamine la configuración generada ni la lógica posterior. Antes de añadir un campo, método, tiempo de espera o política de reintentos a una integración concreta, examina su jerarquía de clases y las implementaciones relacionadas. Sitúa el comportamiento compartido en el nivel más general que realmente lo necesite. Utiliza un mecanismo de reintentos probado con políticas explícitas de intentos y demoras; crea un bucle personalizado solo cuando el mecanismo estándar no pueda expresar el requisito y documenta el motivo. ## Probar en tres capas, de las pruebas unitarias a la evaluación completa del agente Utiliza tres capas complementarias. Las pruebas unitarias aíslan el comportamiento local, las pruebas de integración ejercitan los límites entre herramientas y servicios, y las evaluaciones de agentes verifican el comportamiento integral de la investigación con instrucciones y datos de prueba realistas. El comportamiento local nuevo necesita cobertura unitaria, las integraciones nuevas necesitan cobertura de límites y las investigaciones complejas necesitan casos de evaluación. Mantén alineadas la estructura del código fuente y la de las pruebas. Utiliza simulaciones HTTP en la capa de transporte al probar el comportamiento de las solicitudes, de modo que se ejerciten los encabezados, las URL, los parámetros y los adaptadores en vez de sustituir una función de alto nivel. Ejecuta herramientas reales únicamente en un entorno configurado de forma deliberada y distingue las pruebas deterministas ordinarias de las evaluaciones que requieren credenciales del modelo o servicios externos. ## Diseñar evaluaciones que detecten respuestas inventadas (alucinaciones) Haz que cada instrucción solicite los hechos exactos que comprueba la evaluación. Prefiere valores esperados que solo puedan descubrirse mediante consultas, como un identificador único insertado, un recuento exacto, un título o un código de error. La respuesta esperada debe permanecer oculta para el agente. Si la respuesta es demasiado genérica para demostrar el descubrimiento, exige pruebas de que se llamó a la herramienta correcta. Prueba el descubrimiento, no el reconocimiento. Utiliza nombres de recursos neutros, situaciones realistas e instrucciones que no revelen la implementación ni la solución probable. Evita afirmaciones genéricas que un modelo pueda adivinar a partir de su conocimiento del dominio. Utiliza únicamente etiquetas de prueba registradas, nombres de recursos únicos, versiones fijadas de dependencias o imágenes y salidas de fallo explícitas cuando la configuración no pueda demostrar que el servicio funciona. ## Permitir que varias ejecuciones de prueba compartan recursos en la nube sin romperse entre sí Supón que las evaluaciones respaldadas por la nube de varias ramas pueden solaparse en una misma cuenta. La preparación debe ser idempotente: debe crear o reutilizar recursos sin fallar cuando ya existan. La limpieza nunca debe eliminar un recurso compartido estático que otra ejecución aún pueda estar utilizando; omite la limpieza o limítala a un identificador único dentro del alcance de la ejecución. Verifica el funcionamiento mediante una respuesta real de la API, no solo mediante el estado de disponibilidad. Realiza sondeos con reintentos acotados para gestionar las condiciones de carrera durante la creación, falla pronto si el contenido esperado nunca aparece y captura diagnósticos cuando se agote el tiempo de espera. Reutiliza una infraestructura compartida estandarizada cuando varias pruebas necesiten el mismo servicio, pero mantén aislados los datos y los identificadores de cada prueba. ## Buscar la causa de fallos de pantalla en la terminal y de caídas en la evaluación con registros reales Para los defectos de terminales interactivos, reproduce el problema mediante un pseudoterminal y captura las secuencias de escape sin procesar. Compara el movimiento del cursor y las operaciones de borrado con la altura del marco renderizado y después prueba el renderizador con un flujo en memoria forzado a comportarse como terminal. Corrige el contrato del marco o de actualización que provoca la desviación; no parches a ciegas el movimiento del cursor cuando el comportamiento difiera en la parte inferior del terminal. Para las regresiones en evaluaciones de agentes, compara una traza de referencia con una traza actual de la misma prueba y el mismo modelo antes de confiar en diferencias del código fuente o estadísticas agregadas. Examina las instrucciones renderizadas, el orden de llamadas a herramientas, las métricas por llamada y las pruebas devueltas. Una plantilla puede crecer en el código fuente y reducirse durante la ejecución, mientras que la variación agregada puede ocultar un cambio determinista en cada ejecución. Lee el conjunto de cambios completo de una revisión sospechosa antes de revertir solo el archivo más visible. ## Formatear y revisar solo los archivos del alcance y no hacer push sin permiso Sigue las políticas específicas del repositorio sobre estilo, tipado, pruebas y control de versiones, pero no ejecutes correcciones automáticas amplias, tareas de formato ni comprobaciones de todo el repositorio cuando se sepa que modificarán archivos ajenos, salvo que el usuario o el flujo de trabajo rector lo soliciten expresamente. Limita el formato automático y el análisis estático a los archivos incluidos en el alcance y mantén las revisiones centradas junto con las pruebas correspondientes. Coloca las importaciones y las utilidades compartidas según las convenciones del proyecto, conserva un historial reversible y evita reescribir el historial por la fuerza salvo autorización expresa. Una tarea local no autoriza por sí sola a hacer commit, hacer push, publicar ni modificar el estado externo. Indica qué verificaciones se ejecutaron y qué comprobaciones se excluyeron deliberadamente. ## Actualizar todas las referencias cuando cambie una página o un título de la documentación Utiliza la documentación del repositorio como fuente principal del comportamiento del proyecto antes de consultar el sitio web público. Cuando se mueva una página, cambie un nombre de archivo o se modifique el ancla de un encabezado, busca la ruta y el ancla anteriores en todo el repositorio, incluidos la documentación, las cadenas del código fuente, las guías de nivel superior y los comentarios, y actualiza todas las referencias afectadas. Actualiza la fuente real de navegación del sistema de documentación en lugar de una configuración con un nombre parecido pero inactiva. Conserva la estructura específica del renderizador, incluidas las líneas en blanco obligatorias y una jerarquía válida de encabezados. Evita las listas de capacidades obsoletas y el relleno de seguridad repetitivo; prefiere ejemplos concisos y bloques consolidados de solución de problemas. Cuando añadas una integración, actualiza conjuntamente su descripción general, índice, página dedicada, entrada de navegación y recurso visual.