Un agradecimiento especial a todos los que contribuyeron a este lanzamiento: Stephanie Yuan, Lefan Zhang, Ritvika Pillai, Irene Wang, Carter Williams, TJ Ariyawansa, Gitika Jha, Shoaib Javed y el liderazgo de producto de Vivek Singh.
Pasar los agentes prototipo a producción requiere medir la calidad en múltiples dimensiones. Amazon Bedrock AgentCore Assessments proporciona comprobaciones de modelo de lenguaje grande (LLM) como juez y evaluadores extensibles basados en código que capturan los requisitos específicos del dominio que necesita para evaluar su aplicación agente.
En los servicios financieros y los dominios especializados, las dimensiones críticas de calidad a menudo se extienden más allá del idioma. Un agente de inteligencia de mercado debe cotizar los precios de las acciones dentro de una banda en vivo configurable, seguir un flujo de trabajo obligatorio de identificación de corredores antes de acceder a los perfiles financieros, devolver resultados de herramientas que se ajusten a un estricto esquema JSON y retener información de identificación personal (PII). Estas comprobaciones requieren un código determinista que produzca el mismo resultado en entradas idénticas. También puede resultar costoso ejecutarlos con LLM-as-a-Judge cuando un fragmento de código objetivo es la opción más sencilla.
Con evaluadores personalizados basados en código, puede incorporar una función AWS Lambda como motor de evaluación. Con los evaluadores personalizados basados en código, usted controla la lógica de puntuación: validación estructural y de expresiones regulares, búsquedas de datos externos, llamadas a otros servicios o reglas comerciales. El mismo evaluador se puede utilizar de varias maneras sin requerir tokens del modelo básico (FM) para cada solicitud. En las evaluaciones bajo demanda, actúa como puerta dentro de los flujos de trabajo de desarrollo y los canales de integración y entrega continua (CI/CD). En configuraciones de evaluación en línea, puede calificar el tráfico de producción en vivo. Con control total sobre la lógica de evaluación a través de AWS Lambda, puede adaptar evaluadores personalizados basados en código a sus necesidades. Incluso si los seguimientos provienen de diferentes marcos de agentes, puede utilizar este enfoque para evaluar de forma consistente la calidad de los agentes utilizando su propia lógica.
En esta publicación, implementará cuatro evaluadores de código personalizados basados en Lambda para un agente de inteligencia de mercados financieros, registrará cada uno de ellos en AgentCore y los ejecutará en modo on-demand y en línea. También verá cómo combinar evaluadores personalizados basados en código con evaluadores integrados y cómo llamar a otros servicios de AWS para verificación de hechos fundamentada, detección de PII y alertas en tiempo real.
Dimensiones de calidad adecuadas para la evaluación basada en códigos
Los agentes dependen de resultados de herramientas estructuradas como JSON de búsqueda, recuperación o API comerciales. Un cambio de contrato, un error de análisis o una interrupción del flujo ascendente pueden producir datos con formato incorrecto que el agente entreteje en una respuesta incorrecta. La validación del esquema de respuesta de la herramienta detecta problemas estructurales en el límite de la herramienta y es muy adecuada como verificación basada en código, mientras que los evaluadores de LLM como juez la complementan para juzgar la utilidad y la claridad.
Los agentes cotizan precios, métricas, umbrales y cuotas, y desviaciones tan pequeñas como el 0,1 por ciento pueden cambiar una decisión comercial financiera. Los LLM son propensos a errores aritméticos, mientras que un evaluador basado en código llama al sistema de referencia, calcula la tolerancia y señala cada discrepancia. La precisión numérica frente a una fuente de referencia se verifica más eficazmente de forma determinista.
Los agentes que operan bajo restricciones de órdenes y políticas deben identificar al usuario antes de leer datos confidenciales, capturar aprobaciones antes de ejecutar acciones y seguir una secuencia de herramientas específica para mantener la integridad de los datos. Verificar el cumplimiento del contrato de flujo de trabajo requiere inspeccionar la secuencia de llamadas a herramientas a lo largo de una sesión. Un evaluador basado en códigos verifica que el agente siguió el proceso, y LLM-as-a-Judge mide qué tan bien comunicó el resultado.
Los agentes que trabajan con perfiles, documentos o registros deben ocultar nombres, ID de cuentas, detalles de contacto y secretos. Una respuesta que expone estos datos es una falla de cumplimiento o seguridad. Los evaluadores basados en códigos llaman a servicios de detección de PII o de escaneo de secretos y aplican reglas estrictas sobre el contenido de las respuestas, complementando las puntuaciones de calidad del lenguaje y utilidad.
Junto con los evaluadores de LLM como juez, las verificaciones basadas en códigos validan tanto cómo se comunica el agente como si respetó los contratos, los números, los flujos de trabajo y las reglas de manejo de datos. Esta combinación hace que la confiabilidad del agente pase de “suena bien” a estar verificada por contrato.
Ciclo de vida del evaluador: desde intervalos hasta resultados puntuados
Un evaluador basado en código es una función Lambda registrada en el plano de control de AgentCore. Cuando se ejecuta una evaluación, AgentCore asume un rol de AWS Identity and Access Management (IAM) en su cuenta, invoca Lambda con una carga útil que contiene los intervalos de OpenTelemetry (OTel) del agente y escribe la respuesta de Lambda en Amazon CloudWatch Logs como resultado de la evaluación. La carga útil contiene una versión del esquema, un ID del evaluador, un nombre del evaluador, un nivel de evaluación y un objeto de entrada de evaluación que contiene la matriz de intervalos de OTel para la sesión. Para los evaluadores a nivel de seguimiento, un campo de destino de evaluación separado identifica el seguimiento específico para calificar. Para los evaluadores a nivel de sesión, AgentCore omite el objetivo y Lambda califica la conversación completa.
La respuesta Lambda sigue un contrato fijo. En caso de éxito, devuelve un diccionario con una etiqueta (por ejemplo, PASA o FALLA), una puntuación numérica opcional entre 0,0 y 1,0 y una cadena de explicación opcional. En caso de error, devuelve un diccionario con un código de error y un mensaje de error. Debes incluir una etiqueta en cada respuesta de éxito. Los campos de puntuación y explicación son opcionales, pero alimentan directamente las métricas de CloudWatch y el panel de observabilidad de AgentCore, que le ayuda a depurar cuando sus puntuaciones son bajas. Cada evaluador se ejecuta en uno de los tres niveles establecidos en el registro: TRACE, TOOL_CALL o SESSION, como se muestra en la siguiente figura. Para puntuar el mismo Lambda en varios niveles, regístrelo por separado en cada nivel que apunte a la misma función.
Figura: Los evaluadores basados en código se registran por separado en cada nivel: seguimiento, llamada de herramienta y sesión.
Modos bajo demanda y en línea de evaluadores personalizados basados en código
AgentCore Assessments admite evaluadores basados en código tanto en modo on-demand como en línea. Se utiliza un ID de evaluador único para el desarrollo, las pruebas, las puertas de integración y entrega continuas (CI/CD) y el monitoreo continuo de la producción. El contrato Lambda, incluida la carga útil, el formato de respuesta y la configuración de IAM, sigue siendo el mismo en ambos modos. La siguiente figura ilustra el flujo de evaluación en línea; La evaluación bajo demanda sigue el mismo camino, con la llamada Evaluar API reemplazando el paso de muestreo programado.
Figura 2: Flujo de un extremo a otro para un evaluador basado en código en la evaluación en línea.
Evaluación bajo demanda para el desarrollo y CI/CD
La evaluación bajo demanda se adapta a tres escenarios:
Iteración de desarrollo. Capture una sesión, ejecute el conjunto de evaluadores, inspeccione las puntuaciones y explicaciones de cada evaluador y utilice los comentarios para guiar el siguiente cambio en el mensaje, las definiciones de herramientas o el flujo de trabajo de la memoria. Pruebas de regresión. Mantenga una biblioteca de sesiones representativas, incluidas sesiones que previamente revelaron fallas, y ejecute el conjunto de evaluadores contra ellas en su conjunto de pruebas. Un evaluador que obtiene una puntuación por debajo del umbral indica una regresión. Puerta de implementación de CI/CD. Antes de promover una nueva versión del agente a producción, ejecute el conjunto de evaluadores en un conjunto de sesiones de prueba de humo y bloquee la implementación si falla un evaluador basado en código.
Una sola llamada bajo demanda puede hacer referencia a hasta 10 evaluadores de tipos integrados y basados en código. Para el Agente de tendencias de mercado, un pase previo a la implementación ejecuta los evaluadores integrados de Utilidad y Corrección junto con los cuatro evaluadores basados en código. El resultado combinado confirma la calidad del lenguaje, la integridad del contrato de herramientas, la precisión de los precios, el orden del flujo de trabajo y la seguridad de la PII en una sola pasada.
Evaluación en línea para un seguimiento continuo de la producción.
La evaluación en línea toma muestras continuamente del tráfico de agentes en vivo y lo califica con evaluadores configurados en un cronograma recurrente. Para configurar la evaluación en línea, debe crear una configuración de evaluación en línea una vez a través del plano de control de AgentCore, especificando:
Evaluadores: hasta 10 ID de evaluador, combinando tipos basados en código e integrados Fuente de datos: grupo de registros de CloudWatch y nombre del servicio OTel para los intervalos del agente Muestreo: el porcentaje de sesiones a evaluar (0,01 a 100 por ciento)
La evaluación en línea se adjunta a un agente apuntándolo directamente al agente en AgentCore Runtime o haciendo referencia al grupo de registros de CloudWatch utilizado por el agente. Luego, AgentCore utiliza esta configuración de fuente de datos para encontrar sesiones completadas agrupando intervalos que representan una conversación completa para ese agente y ejecutando una evaluación en ellas.
Puede ajustar la cantidad de tráfico que se evalúa estableciendo el porcentaje de muestreo entre 0,01 y 100 por ciento. También establece un tiempo de espera de sesión, que le indica a AgentCore cuánto tiempo debe esperar después del último lapso antes de considerar una sesión como completa. Este tiempo de espera debe coincidir con la duración típica de la sesión de su agente para evitar calificar sesiones que aún están en progreso.
Una vez habilitada la configuración, AgentCore se encarga de la programación recurrente por usted. Para cada sesión de muestra, lee intervalos de CloudWatch, invoca a cada evaluador que haya configurado y escribe los resultados de la evaluación en un grupo de registros de CloudWatch dedicado a los resultados de la evaluación. Cuando hace esto, AgentCore asume el rol de IAM de ejecución de evaluación definido en la configuración, por lo que los permisos Lambda y CloudWatch se adjuntan a ese rol en lugar de al rol de tiempo de ejecución del agente.
Cada puntuación del evaluador también aparece como una métrica de CloudWatch en formato de métrica integrada en el espacio de nombres Bedrock-AgentCore/Evaluaciones, codificada por el nombre del evaluador y el ID de configuración. Con esto, puede crear paneles de CloudWatch que trazan la validez del esquema, el cumplimiento del flujo de trabajo y la limpieza de la PII junto con la utilidad y la corrección, proporcionando una vista unificada tanto del lenguaje como de la calidad estructural. Además de eso, puede configurar CloudWatch Alarms en estas métricas para alertar a sus operadores cada vez que una dimensión de calidad particular caiga por debajo de un umbral importante.
Descripción general de la solución
En esta solución, utilizamos un Agente de Tendencias de Mercado como ejemplo. Market Trends Agent es un asistente de inteligencia de inversiones creado en LangGraph e implementado en Amazon Bedrock AgentCore Runtime. La muestra completa se encuentra en 02-use-cases/market-trends-agent en el repositorio de muestras de AgentCore. El agente brinda a los corredores financieros datos bursátiles, análisis de noticias de múltiples fuentes y perfiles de corredores almacenados en AgentCore Memory, adaptando el análisis a la estrategia, los intereses y la tolerancia al riesgo de cada corredor.
El agente expone herramientas para la recuperación del precio de las acciones, noticias financieras, búsqueda, extracción de identidades de corredores, lecturas y escrituras de perfiles y generación de informes de mercado. La instrumentación OTel de LangGraph se publica en Amazon CloudWatch a través de AgentCore Observability, lo que convierte al agente en un banco de pruebas para evaluadores basados en código y LLM como juez. Usamos este agente para demostrar cómo configurar evaluaciones personalizadas basadas en código en modos en línea y bajo demanda.
Figura 3: Arquitectura del Agente de Tendencias del Mercado
La muestra incluye cuatro evaluadores que cubren la validación de esquemas, la precisión numérica, el cumplimiento del flujo de trabajo y la detección de PII.
ToolResponseSchemaValidator (nivel de seguimiento): este evaluador filtra los intervalos hasta el seguimiento objetivo, identifica los intervalos de llamadas de herramientas y verifica la respuesta de cada herramienta con un patrón esperado: ticker y precio para datos de acciones, longitud y formato para resúmenes de noticias. StockPriceDriftChecker (nivel de seguimiento): verifica los precios cotizados en las respuestas del agente con una fuente externa de verdad dentro de una tolerancia configurable (2 por ciento predeterminado). Este evaluador extrae pares de ticker más precio del texto de respuesta, obtiene precios de referencia de un punto final de datos de mercado y calcula la desviación porcentual por par. WorkflowContractGSR (nivel de sesión): aplica un contrato de flujo de trabajo de tres pasos durante toda la sesión: identificar al corredor, operar en el perfil del corredor y luego llamar a los datos del mercado y a las herramientas de noticias. Este evaluador reconstruye la lista ordenada de llamadas a herramientas a partir de períodos de sesiones y verifica que cada paso se haya producido en orden. BrokerPIILeakChecker (nivel de sesión): analiza cada respuesta de agente en una sesión en busca de PII mediante la API de Amazon Comprehend DetectPiiEntities. Lambda clasifica las entidades detectadas en tipos de alto riesgo (SSN, tarjeta de pago, cuenta bancaria, identificación gubernamental, credencial) y detalles de contacto de menor riesgo (nombre, correo electrónico, teléfono, dirección), aplicando diferentes umbrales a cada uno. Devoluciones de PII de alto riesgo FALLAN; el uso excesivo de PII de menor riesgo arroja una puntuación parcial con recuentos. Se incluye una variante basada en expresiones regulares para entornos que no pueden depender de Comprehend.
Requisitos previos
Este tutorial requiere 45 minutos de práctica y cuesta menos de $5 en cargos de AWS a las tasas de muestreo predeterminadas. Para seguirlo, necesitas:
Pasos de implementación
La muestra completa, incluido el código del agente, los cuatro Lambdas del evaluador y los scripts de implementación, está disponible en el directorio de agentes de tendencias del mercado. Siga el archivo README allí para completar estos pasos:
Implemente el agente de tendencias de mercado: un único comando uv run python implementar.py aprovisiona el tiempo de ejecución de AgentCore, la memoria, la función IAM y el contenedor Amazon Elastic Container Registry (Amazon ECR). Implemente los evaluadores: uv run python evaluators/scripts/deploy.py empaqueta las cuatro funciones Lambda, crea los roles de IAM, registra cada evaluador con el plano de control de AgentCore y crea una configuración de evaluación en línea con un muestreo del 100 por ciento. Genere tráfico de prueba: uv run python evaluators/scripts/invoke.py ejecuta cuatro escenarios integrados (flujo de trabajo de corredor de ruta feliz, corredor de retorno, cebo de PII con un SSN fabricado y charla anónima) para producir sesiones que ejerciten comportamientos de aprobación, falla y casos límite. Ejecute una evaluación bajo demanda: utilice AgentCore CLI o SDK para evaluar una sesión específica de forma sincrónica, inspeccionar etiquetas y explicaciones por evaluador y validar el comportamiento antes de pasar a producción. Ver resultados de evaluación en línea: uv run python evaluators/scripts/results.py extrae resultados puntuados de CloudWatch, agrupados por evaluador. Los resultados también aparecen como métricas de CloudWatch en el espacio de nombres Bedrock-AgentCore/Evaluaciones para paneles y alarmas.
Una vez que haya completado las instrucciones en el archivo README, puede comenzar a monitorear las métricas de evaluación en la consola AgentCore Observability como se muestra en las siguientes figuras. Si su configuración de evaluación de AgentCore no produce resultados, o si ve errores o puntuaciones de evaluación vacías, puede utilizar la habilidad de diagnóstico de evaluación de AgentCore para solucionar el problema.
Limpieza
Para evitar cargos continuos, elimine todos los recursos creados durante este tutorial. Primero elimine los recursos del evaluador (funciones Lambda, roles de IAM y la configuración de evaluación en línea), luego ejecute el script de limpieza del agente para eliminar el tiempo de ejecución, la memoria, el repositorio de ECR y la infraestructura restante de AgentCore. El archivo README del repositorio proporciona los comandos exactos para ambos pasos en las secciones Evaluadores de limpieza y Limpieza completa de recursos.
Mejores prácticas para utilizar evaluadores personalizados basados en código
Cuando comienza a evaluar los agentes en producción, rápidamente descubre que algunos problemas de calidad son subjetivos mientras que otros son rígidos y se basan en reglas. Los evaluadores personalizados basados en código en AgentCore están diseñados para cubrir esa segunda categoría, de modo que pueda aplicar verificaciones deterministas con su propia lógica. El flujo de trabajo para agregar estos evaluadores es el mismo cada vez, ya sea que esté creando el primero o ampliando un conjunto de evaluación completo.
Decide qué comprobar con el código
Comience por identificar las dimensiones deterministas de calidad en las que desea cero ambigüedad. Estos son los lugares donde el juicio humano o el razonamiento LLM por sí solos no son suficientes. Por ejemplo, restricciones de datos exactas como ID o cantidades que deben coincidir con un formato o valor específico, restricciones estructurales como secuencias de llamadas de herramientas requeridas o pasos de flujo de trabajo, y requisitos de cumplimiento que incluyen políticas de PII o reglas regulatorias que necesitan una aplicación comprobable.
Continúe usando evaluadores de LLM como juez integrados o personalizados para dimensiones subjetivas como utilidad, tono, coherencia, capacidades de razonamiento y calidad conversacional general. Los evaluadores basados en código están ahí para cubrir los aspectos binarios estrictos en los que se desean garantías deterministas.
Para asignar cada problema al lugar correcto de la interacción, elija un nivel de evaluación:
Nivel Granularidad Patrón de invocación Uso típico TRACE Turno de un solo usuario Una invocación de Lambda por seguimiento, distribuida en paralelo Validación de esquema por respuesta, comprobaciones de precisión numérica, escaneo de PII por respuesta TOOL_CALL Invocación de herramienta única Una invocación de Lambda por intervalo de coincidencia, identificada por el objetivo de evaluación Validación de parámetros de herramienta, verificación de la frescura de la recuperación SESSION Conversación completa Una invocación de Lambda por sesión, sin objetivo de evaluación Comprobaciones de ordenamiento de flujo de trabajo, escaneos de PII en toda la sesión, evaluación de objetivos-éxito
Esta asignación le impide complicar demasiado las comprobaciones para conectar cada regla de negocio al ciclo de vida del agente.
Prueba contra modos de falla reales en modo bajo demanda
Por lo general, se necesita evidencia sobre el tráfico real antes de que un nuevo evaluador tenga voz en las decisiones de implementación o en las alertas de guardia, y ahí es donde la evaluación bajo demanda encaja naturalmente. En lugar de ir directamente a una adopción amplia, usted ejercita al evaluador en un pequeño conjunto de sesiones conocidas y confirma que detecta de manera confiable los problemas específicos que le interesan, con explicaciones que resaltan claramente el lapso o la herramienta responsable del fracaso. Si el evaluador recurre a sistemas externos, como un detector de PII o un motor de políticas, este también es el momento de validar que los permisos, los tiempos de espera y otros detalles de integración se comportan como se esperaba.
El mismo mecanismo puede luego convertirse en parte de su canal de CI/CD como puerta de implementación. Una vez que se sienta cómodo con el desempeño del evaluador en un conjunto de pruebas seleccionado, invoca la API de evaluación bajo demanda desde la canalización y falla la compilación cuando señala problemas críticos. Esto le brinda una manera de hacer cumplir garantías estrictas, como la validez del esquema, la corrección numérica o la higiene de la PII, antes de que los cambios lleguen a producción, mientras mantiene la evaluación en línea enfocada en detectar derivas y fallas de cola larga en lugar de regresiones obvias.
Conéctelo a un monitoreo continuo
Usted promueve un evaluador personalizado a evaluación en línea después de estar seguro de que se comporta de la manera esperada, permitiéndole calificar el tráfico en vivo en lugar de simplemente realizar pruebas. En la práctica, eso significa definir una configuración de evaluación en línea donde el ID del evaluador se ubica junto a los evaluadores integrados en los que ya confía, y la fuente de datos está conectada al grupo de registros de CloudWatch de su agente y al nombre del servicio OTel. El porcentaje de muestreo se convierte entonces en su dial principal para equilibrar la cobertura y el costo: los agentes de bajo volumen a menudo tienen sentido al 100 por ciento, por lo que se inspecciona cada sesión, mientras que los agentes de alto volumen generalmente aterrizan en el rango del 10 al 20 por ciento para preservar la señal sin sobrecargar su presupuesto.
Una vez implementado esto, los resultados fluyen hacia un grupo de registro de resultados dedicado y cada puntuación del evaluador se muestra como una métrica de CloudWatch. Esas métricas le brindan la materia prima para crear paneles que muestren señales de evaluación personalizadas y para conectar alarmas de CloudWatch que notifiquen al equipo cada vez que una métrica cae por debajo del umbral que más le interesa. En ese momento, sus evaluadores ya no ocultan los detalles de implementación; son señales visibles y rastreables a las que puede señalar cuando necesita comprender si la calidad ha variado y si el sistema aún satisface los estándares de cumplimiento para un caso de uso particular.
Conclusión
Los evaluadores basados en códigos extienden la cobertura de AgentCore a las dimensiones de calidad que requieren una lógica determinista. En el modo bajo demanda, actúan como comprobaciones de desarrollo y puertas de implementación de CI/CD, devolviendo puntuaciones sincrónicas y explicaciones a nivel general. En el modo en línea, el mismo evaluador registrado califica las sesiones de producción en vivo junto con los evaluadores integrados de LLM como juez y emite resultados como métricas de CloudWatch. Junto con los evaluadores integrados, los evaluadores personalizados basados en códigos mueven la confiabilidad de los agentes de "suena bien" a un paradigma verificado por contrato. Debido a que la lógica reside en su propia Lambda, puede desarrollar comprobaciones a medida que cambian las reglas comerciales. Un único registro de evaluador sirve para el desarrollo local, las puertas de CI/CD y el monitoreo continuo de la producción, lo que brinda a su equipo una señal de calidad constante desde el prototipo hasta la escala.
Para comenzar, revise la documentación de evaluaciones de Amazon Bedrock AgentCore, identifique las propiedades estructurales y de cumplimiento de su agente que requieren comprobaciones deterministas e implemente los evaluadores de muestra del repositorio amazon-bedrock-agentcore-samples.
Sobre los autores
Bharathi Srinivasan
Bharathi Srinivasan es científico de datos de IA generativa en AWS. Le apasiona la IA responsable para aumentar la confiabilidad de los agentes de IA en escenarios del mundo real. Bharathi guía a los equipos internos y a los clientes de AWS en su viaje hacia la IA responsable. Ha presentado su trabajo en varias conferencias sobre aprendizaje automático.
Shoaib Javed
Shoaib Javed es gerente de ingeniería en AWS y dirige los equipos de evaluaciones de Amazon Bedrock AgentCore. Shoaib disfruta construyendo sistemas de IA Agentic a escala mundial y lidera equipos que actualmente están superando estas fronteras ayudando a los clientes a promover Agentes desde el prototipo hasta la producción. En su tiempo libre le gusta cocinar y ser padre.
Hardik Vasa
Hardik Vasa es arquitecto senior de soluciones en AWS. Se centra en la IA generativa y las tecnologías sin servidor, ayudando a los clientes a aprovechar al máximo los servicios de AWS. Hardik comparte sus conocimientos en varias conferencias y talleres. En su tiempo libre, le gusta aprender sobre nuevas tecnologías, jugar videojuegos y pasar tiempo con su familia.