AgentOps: monitoree y gobierne los agentes de IA con IBM Telemetry mediante watsonx Orchestrate

A medida que los agentes de IA se vuelven más sofisticados y autónomos, comprender su comportamiento, rendimiento y procesos de toma de decisiones es crítico para garantizar la confiabilidad y la gobernanza. AgentOps, la práctica de monitorear, observar y gestionar agentes de IA en producción, proporciona la visibilidad necesaria para construir sistemas de IA agéntica confiables.

Este tutorial proporciona una guía paso a paso para configurar y usar IBM Telemetry con watsonx Orchestrate Developer Edition para monitorear y gestionar agentes de IA. Aprenderá cómo habilitar la observabilidad para los agentes de IA y analizar su comportamiento en profundidad, desde llamadas individuales de LLM hasta flujos de trabajo completos de varios pasos.

Al final de este tutorial, podrá:

• Instalar y configurar watsonx Developer Edition localmente
• Habilitar IBM Telemetry para una observabilidad completa del agente
• Importar y probar un agente de IA preconfigurado con integración de herramientas externas
• Analizar el comportamiento del agente mediante rastreos detallados, tareas, tramos y flujos de trabajo
• Depurar problemas y optimizar el rendimiento del agente mediante el uso de analytics avanzados

IBM Telemetry es el marco de observabilidad nativo de watsonx Orchestrate que captura información detallada sobre cómo los agentes de IA ejecutan las solicitudes. Registra cada paso del ciclo de vida del agente, desde las decisiones de enrutamiento y la construcción de instrucciones hasta las invocaciones de LLM y las llamadas a herramientas, lo que proporciona una visibilidad completa del comportamiento del agente.

Con IBM Telemetry, se puede realizar un seguimiento de las métricas de rendimiento, monitorear el costo de LLM, identificar errores y asegurarse de que los agentes funcionen según lo previsto. IBM Telemetry proporciona observabilidad de nivel empresarial diseñada para entornos de producción y sistemas de IA a escala.

Antes de comenzar, asegúrese de que los siguientes requisitos previos estén instalados y configurados en su sistema:

• Python 3.8+ (consulte con python --version )
• 16 GB de RAM como mínimo
• watsonx Orchestrate Developer Edition a través de watsonx Orchestrate ADK

Esta guía incluye los pasos de instalación de ADK.

• Cuenta de watsonx Orchestrate Prueba gratuita de 30 días disponible si no tiene una cuenta.
• Clave de API de watsonx Orchestrate, generada a partir de su panel de IBM® Cloud.

Los pasos de autorización se proporcionan más adelante en esta guía.

Para comenzar, clone el repositorio de GitHub usando https://github.com/IBM/ibmdotcom-tutorials.git como la URL HTTPS. Para conocer los pasos detallados sobre cómo clonar un repositorio, consulte la documentación de GitHub.

Abra el repositorio en su entorno de desarrollo integrado (IDE) preferido (por ejemplo, Visual Studio Code) y localice la carpeta del proyecto de este tutorial: wxo-agentops  . Este directorio es donde trabajará a medida que siga el proceso.

IBM watsonx Orchestrate Agent Development Kit (ADK) es una herramienta de CLI que simplifica la instalación, configuración y gestión de watsonx Orchestrate Developer Edition.

Para usar ADK, debe conectarlo a un entorno existente de watsonx Orchestrate. Si aún no tiene una cuenta de watsonx Orchestrate, puede registrarse para una prueba gratuita de 30 días. Si ya tiene una cuenta, puede usarla para proporcionar las credenciales de entorno que necesita ADK.

Estos pasos sirven como guía para la instalación mediante un entorno virtual de Python, que es el enfoque recomendado para mantener las dependencias aisladas. Para obtener métodos de instalación alternativos e instrucciones detalladas, consulte la documentación Primeros pasos con ADK.

Cree un nuevo entorno virtual de Python en el directorio de su proyecto:

Este paso crea una carpeta .venv  que contiene un entorno Python aislado.

El comando de activación varía según el sistema operativo.

macOS y Linux

Windows

Una vez activado, la instrucción del terminal debería cambiar para indicar que está trabajando dentro del entorno virtual, que normalmente muestra (.venv ) al principio de la instrucción.

Con el entorno virtual activado, instale ADK mediante pip:

Este comando descarga e instala ADK junto con todas sus dependencias. La instalación puede tardar unos minutos.

Nota: Si tiene instalada una versión anterior de ADK (>2.0 ), ejecute pip install --upgrade ibm-watsonx-orchestrate . Es posible que también deba ejecutar los pasos de solución de problemas del paso 4b.

ADK utiliza un archivo .env  para autenticar sus credenciales de usuario y configurar watsonx Orchestrate Developer Edition. Las variables de entorno que se necesitan dependen del método de autenticación elegido. Este tutorial utiliza el método de cuenta de watsonx Orchestrate, que es el enfoque más sencillo para comenzar.

Para obtener métodos de autenticación alternativos e instrucciones detalladas de configuración, consulte la documentación del archivo de configuración del entorno.

Dentro del directorio wxo-agentops, cree un archivo  .env  copiando la plantilla proporcionada:

Abra el archivo  .env  en el editor de texto y configure los siguientes dos campos esenciales:

• WO_INSTANCE : esta URL es la instancia de watsonx Orchestrate. Puede encontrar esta información mediante el registro en la cuenta de watsonx Orchestrate y navegando hasta los detalles de la instancia. Haga clic en el icono del perfil > Configuración y, a continuación, seleccione la pestaña Detalles de la API. Para obtener instrucciones detalladas sobre cómo comenzar con la API, consulte la documentación de watsonx Orchestrate.

La URL sigue este formato:

Copie y pegue la URL de la instancia de servicio para reemplazar el valor de la plantilla en el archivo .env . La región (por ejemplo, us-south  depende de la ubicación geográfica).

• WO_API_KEY : esta clave es la clave de interfaz de programación de aplicaciones (API) de watsonx Orchestrate, que autentica la conexión a los servicios de IBM Cloud. Puede generar o recuperar esta clave desde el panel de la cuenta de IBM Cloud. Reemplace  <your-api-key>  con la clave de API real. Para obtener instrucciones paso a paso sobre cómo generar una clave de API, consulte la documentación de inicio.

Mantenga segura su clave de API y nunca la comprometa con el control de versiones. El archivo  .env  ya debería estar incluido en .gitignore  para evitar la exposición accidental. 

Ahora ya puede instalar watsonx Orchestrate Developer Edition, que ejecutará una instancia local del servidor Watsonx Orchestrate en su máquina. Este paso también habilita IBM Telemetry, lo que le brinda acceso inmediato a las características de observabilidad.

Descripción del comando de instalación

ADK proporciona un único comando que maneja todo el proceso de instalación:

Analicemos lo que hace este comando:

• orchestrate server start : inicializa e inicia el servidor watsonx Orchestrate Developer Edition
• -e <path-.env-file> : señala el archivo de configuración que contiene las credenciales
• --with-ibm-telemetry : habilita el marco de observabilidad nativo de IBM Telemetry

Ejecute el comando desde el directorio wxo-agentops:

El siguiente comando inicia el servidor watsonx Orchestrate Developer Edition inicializando el entorno del servidor:  orchestrate server start -e <path-.env-file> . Agregar el indicador --with-ibm-telemetry  habilita IBM Telemetry, su marco de observabilidad nativo.

Ejecute este comando para instalar el servidor watsonx Orchestrate con IBM Telemetry:

Este comando crea contenedores internos gestionados por ADK para:

• El servidor watsonx Orchestrate
• Bases de datos PostgresSQL y Redis
• Servicios de IBM Telemetry
• Dependencias de soporte

ADK configura automáticamente una red virtual que permite que estos contenedores se comuniquen entre sí en http://localhost:3000 .

El proceso de instalación puede tardar varios minutos, especialmente en la primera ejecución, ya que se descargan las imágenes necesarias. Una instalación exitosa produce resultados similares a este ejemplo:

Si ve este mensaje, ¡felicidades! Su entorno local de watsonx Orchestrate con IBM Telemetry ya se está ejecutando.

Si la instalación falla o se bloquea, intente los siguientes pasos:

1. Restablecer el servidor:

Este comando detiene y elimina todos los contenedores creados para watsonx Orchestrate, lo que le permite empezar de cero.

2. Reiniciar la instalación:

Después de reiniciar, ejecute el comando de inicio nuevamente:

3. Comprobar el estado del contenedor de los registros del servidor:

Puede ver los registros de servicio del servidor Orchestrate para comprobar si hay advertencias o errores:

Si los pasos anteriores no funcionan, reinicie el servidor y elimine completamente el entorno del servidor: orchestrate server purge  y reinstale.

Con el servidor watsonx Orchestrate instalado correctamente, ahora necesita activar su entorno local e iniciar la interfaz de chat donde interactuará con sus agentes de IA.

watsonx Orchestrate ADK admite múltiples entornos (local, desarrollo, producción, etc.). Necesita activar explícitamente el entorno local que creó:

Debería recibir confirmación de que el entorno está activo:

Esto establece el entorno local como contexto predeterminado para todos los comandos ADK posteriores. Cualquier agente, herramienta o configuración con la que trabaje ahora se dirigirá a esta instancia local.

Inicie el servicio de interfaz de usuario (IU) de chat de watsonx Orchestrate con el siguiente comando:

Este comando inicializa la interfaz de chat web y la abre automáticamente en su navegador predeterminado. Debería ver un resultado similar a:

La interfaz de chat proporciona una manera fácil de interactuar con sus agentes de IA. Si el navegador no se abre automáticamente, puede navegar manualmente a http://localhost:3000/chat-lite.

Una vez que se carga la interfaz de chat, debería ver una ventana de chat limpia y lista para la interacción. En esta etapa, aún no ha importado ningún agente, por lo que la interfaz estará casi vacía. Ese resultado es el esperado; agregará su primer agente en el siguiente paso.

Ahora que su entorno está configurado, es hora de importar un agente de IA preconfigurado que demuestre las capacidades de monitoreo de IBM Telemetry. Este agente meteorológico utiliza una herramienta API externa para obtener datos meteorológicos en tiempo real, lo que le brinda un ejemplo práctico para observar y analizar.

El agente meteorológico es un punto de partida ideal porque:

• Demuestra el uso de herramientas: muestra cómo los agentes llaman a API externas
• Proporciona un comportamiento claro y observable: cada solicitud sigue un patrón predecible
• Genera datos de telemetría significativos: produce rastreos enriquecidos que puede analizar en IBM Telemetry
• Incluye escenarios de error: le ayuda a comprender cómo la telemetría maneja las fallas
• Ilustra la automatización: elimina la búsqueda manual de datos mediante acciones del agente

Desde la raíz del proyecto (wxo-agentops ), navegue a la carpeta Weather Agent:

Este directorio contiene dos archivos de configuración YAML:

• get_weather.yaml : define la herramienta de API meteorológica
• weather_agent.yaml : define el agente que utiliza esta herramienta

Las herramientas son capacidades reutilizables que los agentes pueden invocar para realizar acciones específicas. Importe primero las herramientas get_weather  :

El indicador --kind openapi  señala que esta herramienta utiliza una especificación OpenAPI para definir su interfaz. Debería ver la confirmación de que la herramienta se importó correctamente.

Ahora importe el agente que utilizará esta herramienta:

Este comando registra el agente meteorológico en su entorno local de watonsx Orchestrate. El agente está preconfigurado con:

• Instrucciones sobre cómo interpretar los datos meteorológicos
• Permiso para llamar a la herramienta  get_weather  
• Comportamiento alternativo para ubicaciones no válidas

Regresa al navegador donde se está ejecutando la interfaz de chat. Es posible que deba actualizar la página para ver el agente recién importado.

Haga clic en el menú desplegable del agente (normalmente ubicado en la parte superior de la interfaz de chat) y seleccione Weather_Agent en la lista.

Con el agente meteorológico seleccionado, intente hacer algunas preguntas para generar datos de telemetría:

Consultas de ejemplo:

• “¿Cómo es el clima en la ciudad de Nueva York?”
• “¿Puedes decirme la temperatura actual en Londres?”
• “¿Cuál es el clima en Tokio?”
• “¿Está lloviendo ahora mismo en Seattle?”

El agente procesará cada solicitud de la siguiente manera:

1. Comprendiendo su consulta
2. Extrayendo la ubicación
3. Llamando a la herramienta  get_weather  con las coordenadas adecuadas
4. Interpretando los datos meteorológicos
5. Respondiendo en lenguaje natural

IBM Telemetry captura cada interacción que tiene con el agente meteorológico. El sistema está registrando:

• El contexto completo de la conversación
• Cada invocación de LLM y los tokens utilizados
• Las llamadas a herramientas con sus entradas y salidas
• Las decisiones de enrutamiento y pasos del flujo de trabajo
• Los tiempos de ejecución y métricas de rendimiento
• Cualquier error o excepción que ocurra
• Interacciones con proveedores externos y sus tiempos de respuesta

En el siguiente paso, explorará estos datos de telemetría en detalle para comprender exactamente cómo se comporta el agente.

Ahora viene la parte más contundente de este tutorial: usar IBM Telemetry para obtener una visibilidad profunda del comportamiento del agente. IBM Telemetry proporciona múltiples vistas y herramientas de analytics que le permiten comprender todos los aspectos de cómo el agente procesa las solicitudes.

Abra el navegador y acceda a https://localhost:8765/?serviceName=wxo-server. La interfaz proporciona repeticiones de sesiones que le permiten repasar las interacciones de los agentes anteriores para su análisis.

Nota: La URL utiliza  https  pero debido a que este espacio es un entorno de desarrollo local, es posible que su navegador muestre una advertencia de seguridad sobre un certificado autofirmado. Este mensaje es normal y puede continuar sin problemas en su entorno local.

Cuando aparezca la pantalla de inicio de sesión, ingrese cualquier nombre (para identificar su sesión local) y haga clic en Iniciar sesión.

Accederá al panel principal de IBM Telemetry.

El panel muestra una lista de rastreos recientes, cada uno de los cuales representa una única interacción del usuario con un agente. Haga clic en el primer rastreo en el panel Rastreo y selección de grupos para ver analytics sobre su chat más reciente con el agente meteorológico.

Este paso lleva a la pantalla Analytics de agentes, que sirve como centro para entender el comportamiento del agente.

La pantalla Analytics de agentes proporciona una descripción general del rastreo seleccionado, que incluye:

• Estadísticas resumidas: tiempo total de ejecución, uso de tokens, estimaciones de costos y datos de evaluación comparativa
• Información del agente: qué agente manejó la solicitud
• Consulta del usuario: la pregunta original formulada
• Vista previa de la respuesta: la respuesta final del agente
• Indicadores de estado: éxito, advertencias o errores

Esta vista de alto nivel le brinda insight inmediato sobre si el agente se desempeñó como se esperaba y con qué eficiencia operó.

La sección Tareas es donde pasará la mayor parte del tiempo analizando el comportamiento del agente. Proporciona una línea de tiempo visual paso a paso de todo lo que hizo el agente durante una solicitud (cada llamada de LLM, invocación de herramientas, decisión de enrutamiento y generación de resultados).

Las tareas se organizan jerárquicamente para reflejar cómo el agente ejecutó realmente el flujo de trabajo, lo que facilita la comprensión de la secuencia de operaciones y sus relaciones.

Examinemos la ruta de ejecución estándar para una solicitud de agente de watsonx Orchestrate. El rastreo del agente meteorológico debe mostrar una estructura similar a este ejemplo:

Este flujo de trabajo muestra todo el ciclo de vida de una sola consulta de usuario. Esto es lo que representa cada tarea:

• 0:_ROOT : el tramo de nivel superior que contiene todas las tareas secundarias. Piense en esta carpeta como la que contiene toda la ejecución del agente. Define el tiempo de inicio y finalización del rastreo completo, desde el momento en que la solicitud ingresa al sistema hasta que se entrega la respuesta final.

Este enfoque es importante porque la duración de la tarea raíz le indica la latencia total que experimentó el usuario. Si el número es demasiado alto, puede analizar sus tareas secundarias para identificar cuellos de botella.

• 0.0:agent_style_router : la tarea de enrutamiento determina qué agente debe manejar el mensaje y clasifica la solicitud en un estilo de manejo. El enrutador analiza la solicitud entrante y decide si requiere manejo conversacional, ejecución basada en herramientas, generación aumentada por recuperación (RAG, por sus siglas en inglés) u orquestación multiagente.

El enrutador garantiza que se invoque la lógica descendente correcta. Si las solicitudes se desvían incorrectamente, aquí es donde identificaría el problema.

• 0.1:agent : el contexto de ejecución del agente principal que orquesta toda la solicitud. Esta tarea ensambla la instrucción a partir de las interacciones del sistema, el historial de conversaciones y las respuestas de la herramienta. Aplica reglas y políticas de orquestación y prepara entradas para el LLM. Esta tarea determina qué tipo de llamada al LLM realizar.

Este paso es donde ocurre la “inteligencia” de la orquestación. La tarea del agente garantiza que el LLM reciba todo el contexto que necesita para tomar decisiones informadas.

• 0.1.0:WatsonxChatModel.chat : la llamada real al LLM donde recibe la instrucción completa y decide si llamar a una herramienta, pedir aclaraciones o producir una respuesta directa. Genera la respuesta, ya sea en texto o en llamadas estructuradas a herramientas.

Este paso es el paso de “pensar” donde el modelo procesa la información y toma decisiones. Los problemas de uso de tokens, latencia y calidad se derivan de esta tarea. Si su agente es lento o costoso, este paso suele ser el principal contribuyente.

• 0.2:answer : el paso final en la cadena toma la salida del LLM y le da formato para su entrega. Esta tarea convierte la salida sin procesar del LLM en el formato de respuesta final y aplica cualquier regla de posprocesamiento o formato. Finalmente, devuelve la respuesta a la interfaz de chat.

Esta tarea garantiza que el usuario reciba una respuesta con el formato adecuado. Si las respuestas aparecen truncadas o con un formato incorrecto, este es el paso en el que se debe investigar.

Resumen del flujo de trabajo de tareas

Para resumir el flujo de trabajo completo:

1. El enrutador decide cómo manejar la solicitud
2. El agente prepara el contexto y la lógica de orquestación
3. El LLM genera la respuesta o las llamadas a herramientas
4. La respuesta formatea y devuelve el resultado final

Todo este flujo de trabajo está envuelto en el contenedor de solicitudes ROOT, lo que le brinda una imagen completa de la ejecución del agente de principio a fin. Este nivel de observabilidad es esencial para los equipos de MLOps y DevOps que gestionan operaciones de agentes y pipelines complejos a escala.

Cada tarea en la jerarquía contiene tres categorías de atributos que proporcionan metadatos detallados sobre lo que la tarea consumió y produjo:

1. Atributos de entrada: muestran todo lo que la tarea recibió antes de su ejecución: mensajes, respuestas de la herramienta, instrucciones del sistema, el estado interno.

Ejemplo: Para la tarea WatsonxChatModel.chat , los atributos de entrada incluirían la instrucción completamente ensamblada con indicaciones del sistema, historial de conversaciones y cualquier resultado de la herramienta que necesite interpretarse.

2. Atributos de salida: muestran lo que produjo la tarea, incluyendo: finalizaciones de LLM, llamadas a herramientas y decisiones.

Ejemplo: la misma tarea WatsonxChatModel.chat podría generar una respuesta de lenguaje natural o una llamada a herramienta estructurada como get_weather(latitude=40, longitude=-74) .

3. Atributos generales: proporcionan metadatos de telemetría: uso de tokens, información de tiempo, identificadores como ID únicos e información del modelo.

Ejemplo: puede ver que una tarea usó 450 tokens de entrada y 120 tokens de salida, tardó 1.2 segundos en ejecutarse y usó el ibm/granite-3.1-8b-instruct model .

Cómo usar los atributos de las tareas

En conjunto, estos atributos permiten entender completamente lo que el modelo vio, qué decidió y cómo respondió.

Este nivel de detalle es invaluable para la depuración, optimización y validación.

Cada tarea incluye métricas relacionadas con el rendimiento y los costos que resumen cómo se ejecutó la tarea. Estas métricas proporcionan datos cuantitativos sobre el rendimiento del agente.

Las métricas clave incluyen:

• Tiempo total de ejecución: cuánto tiempo tomó la tarea de principio a fin
• Recuento de llamadas al LLM: cuántas veces se invocó el modelo de lenguaje
• Número de llamadas de herramientas: ¿cuántas veces se llamaron a herramientas externas?
• Uso de tokens: tokens de entrada, tokens de salida y tokens totales consumidos
• Estimaciones de costos: costos aproximados basados en el uso de tokens (cuando los datos de precios están disponibles)
• Distribución de subtareas: cómo se distribuyó el trabajo entre las tareas secundarias

Estas métricas ayudan a optimizar el rendimiento y depurar el comportamiento del agente. También pueden identificar tareas lentas que podrían ponerse en paralelo o almacenarse en caché. Esta vista es integral para la planificación de la capacidad porque le permite comprender los recursos para escalar y realizar un seguimiento del uso de tokens para controlar los gastos.

Por ejemplo, si observa que un seguimiento tardó 8 segundos, pero solo 0.5 segundos en llamadas al LLM, sabe que el cuello de botella está en otra parte (probablemente en la ejecución de la herramienta o la latencia de la red).

Si bien las tareas le muestran el flujo de trabajo lógico de su agente, los tramos representan las operaciones subyacentes a nivel de sistema que ocurren durante la ejecución. Al hacer clic en la pestaña Tramos, se revela lo que la plataforma está haciendo internamente para procesar cada solicitud.

Los tramos proporcionan visibilidad de los pasos de ejecución de bajo nivel registrados por el marco de orquestación (en este caso, LangGraph, un marco de código abierto que se ejecuta dentro del servidor wxo). Cada tramo representa una operación discreta como:

• Enrutar la solicitud al agente correcto (agent_style_router )
• Invocar el agente e inicializar su contexto (agent.task )
• Crear instrucciones y contexto a partir de plantillas (ChatPromptTemplate.task )
• Llamar al LLM con la instrucción ensamblada (WatsonxChatModel.chat )
• Devolver resultados al usuario (answer.task )

Si bien las tareas muestran los pasos lógicos de la ejecución del agente (lo que el agente está tratando de lograr), los tramos muestran los pasos técnicos (cómo el sistema lo lleva a cabo). Esta vista dual brinda tanto la comprensión de alto nivel como la capacidad de depuración de bajo nivel.

Ejemplo: una sola tarea como 0.1:agent puede contener múltiples tramos que representan consultas a la base de datos, búsquedas en la caché y carga de la configuración. Estas operaciones se realizan entre bastidores para apoyar la ejecución del agente.

Cada tramo incluye etiquetas que proporcionan metadatos y contexto adicionales. Estas etiquetas son esenciales para filtrar, depurar y analizar el rendimiento de los agentes.

Las etiquetas de tramos comunes incluyen:

• Identificación del agente: agent_id , agent_name
• Seguimiento de la sesión:  thread_id , session_id , conversation_id
• Contexto del flujo de trabajo: step_number , workflow_path , parent_span_id
• Datos de rendimiento: token_count , duration_ms , model_name
• Detalles de la solicitud: tool_calls , input_preview , output_preview

Los tramos son útiles para rastrear la latencia, comprender las fallas al ver qué componente interno falló, analizar patrones filtrando tramos por etiqueta para identificar tendencias y hacer referencias cruzadas vinculando tramos a través de múltiples rastreos mediante el uso de ID de sesión.

Por ejemplo, si el agente se bloquea ocasionalmente, usted puede filtrar los tramos por duración para identificar qué operaciones internas están tardando inesperadamente, tal vez una consulta a la base de datos o una llamada de red a un servicio externo.

La pestaña Flujos de trabajo proporciona una visualización jerárquica llamada Árbol de ejecutables, que muestra la estructura de ejecución completa del flujo de trabajo del agente. Esta visión es especialmente útil para entender sistemas complejos multiagente y patrones de ejecución anidados.

En la infraestructura watsonx Orchestrate, un ejecutable es una unidad de trabajo o tarea que se puede ejecutar. Los ejecutables pueden ser:

• Operaciones simples: una sola llamada al LLM o invocación de herramientas
• Flujos de trabajo compuestos: varios ejecutables encadenados
• Ramas condicionales: diferentes rutas de ejecución basadas en condiciones
• Ejecuciones paralelas: múltiples ejecutables ejecutándose simultáneamente

El árbol ejecutable muestra las relaciones principales y secundarias, lo que facilita ver:

• Qué tareas desencadenan otras: seguir la cadena de ejecución
• Ejecución paralela frente a secuencial: comprender la concurrencia del flujo de trabajo
• Lógica de ramificación: cómo las decisiones llevan a diferentes rutas de ejecución
• Profundidad del flujo de trabajo: qué tan anidada está la lógica del agente

Para agentes simples como el agente meteorológico, la vista del flujo de trabajo refleja estrictamente la vista de tareas. Sin embargo, los flujos de trabajo se vuelven invaluables cuando se trabaja con:

• Sistemas multiagente: múltiples agentes especializados que colaboran en una tarea
• Orquestación compleja: agentes que eligen dinámicamente entre diferentes herramientas o subagentes
• Refinamiento iterativo: agentes que recorren los pasos hasta que se cumple una condición
• Enrutamiento condicional: flujos de trabajo que se ramifican con base en resultados intermedios
• Arquitecturas escalables: diseño de flujos de trabajo que manejan cargas del mundo real de manera eficiente

Por ejemplo, imagine un agente que primero verifica si una consulta requiere una búsqueda web, luego decide entre usar una herramienta de calculadora o una herramienta de consulta de base de datos y finalmente valida el resultado antes de responder. El árbol de ejecutables mostraría claramente toda esta estructura de ramificación.

Puede interactuar con el árbol de la siguiente manera:

• Expandir/colapsar los nodos: centrarse en secciones específicas del flujo de trabajo
• Hacer clic en los nodos: pasar a la información detallada de la tarea
• Seguir las rutas de ejecución: rastrear cómo fluyen los datos a través de la ventana
• Identificar los cuellos de botella: detectar dónde los flujos de trabajo se vuelven ineficientes

La visualización hace que la depuración de flujos de trabajo sea significativamente más fácil que intentar seguir registros de texto o solo rastrear datos.

La pestaña Eval (evaluación) proporciona una vista de control de calidad y monitoreo que mide la exactitud y confiabilidad de la ejecución del agente. Este paso es donde se pasa de observar lo sucedido a evaluar qué tan bien sucedió.

La pestaña Eval muestra resultados de la evaluación de calidad a través de barreras:

• Éxito de la tarea: qué tareas se completaron y cuáles fallaron
• Calidad de los resultados: si los resultados coincidieron con lo esperado o los criterios de calidad
• Puntuaciones de rendimiento: métricas cuantitativas que indican los niveles de éxito
• Análisis de errores: categorización y gravedad de las fallas
• Validación de casos de uso: si el comportamiento del agente coincide con los casos de uso previstos

Las evaluaciones le ayudan a monitorear la confiabilidad al rastrear la congruencia con la que su agente produce resultados correctos, identificar cuándo los cambios deterioran el rendimiento del agente, priorizar las mejoras y generar confianza al validar que los agentes funcionan correctamente antes del despliegue en producción.

Puede aprovechar las mediciones de evaluación para configurar alertas, realizar un seguimiento de las mejoras, identificar patrones y utilizar el feedback para guiar el desarrollo para mejorar las instrucciones o herramientas.

Si observa que el 15 % de las consultas meteorológicas fallan en la evaluación, puede investigar esos rastreos específicos para comprender si el problema es un mal manejo de entradas, fallas de API o un formato de respuesta incorrecto.

La pestaña Problemas proporciona una vista centralizada de todo lo que salió mal durante la ejecución del flujo de trabajo. Esta pestaña es el primer lugar al que acudir para depurar fallas o comportamientos inesperados del agente.

La pestaña Problemas muestra problemas como:

• Llamadas a la API fallidas: servicios externos que devuelven errores
• Fallas en la ejecución de herramientas: herramientas que se bloquearon o que se agotó el tiempo de espera
• Entradas faltantes: los datos requeridos no están disponibles cuando es necesario
• Excepciones del modelo: errores en el LLM como límites de token o entradas no válidas
• Errores de validación: datos que no cumplen con los formatos esperados
• Errores de tiempo de espera: operaciones que excedieron los límites de tiempo
• Fallas de tiempo de ejecución no manejadas: excepciones inesperadas en el código del agente

En la captura de pantalla anterior, puede ver un Error de herramienta que se produjo cuando la API meteorológica devolvió un error 424 (Dependencia fallida) o 404 (No encontrado). La pestaña Problemas muestra:

1. El tipo de error: “Error de herramienta”
2. La herramienta específica: get_weather
3. La respuesta de error: respuesta completa de la API que muestra la falla
4. Un enlace directo: haga clic para ir directamente a la tarea donde falló

Este enfoque facilita entender qué salió mal sin tener que buscar en registros o datos de rastreo.

La pestaña Problemas es especialmente valiosa porque agrega fallas en lugar de obligarlo a buscar tareas individuales. Proporciona un contexto completo al incluir detalles completos del error y datos relacionados, mientras que los niveles de gravedad permiten una clasificación rápida para que pueda priorizar qué problemas tratar primero. Los enlaces directos a las tareas de origen significan que un clic le lleva al punto de ejecución exacto donde las cosas salieron mal.

La pestaña Trayectoria proporciona una vista cronológica, al estilo de una conversación, de la interacción del agente entre el usuario y cualquier herramienta que el agente invoque. Esta vista es invaluable para comprender el contexto completo y el flujo del comportamiento del agente.

La vista Trayectoria es útil porque permite ver exactamente cómo el agente procesa las solicitudes de principio a fin, dándole una visión completa del comportamiento del agente. Puede validar la integración de herramientas asegurándose de que las herramientas se llamen con los parámetros correctos y reciban las respuestas adecuadas. Al depurar respuestas inesperadas, la trayectoria le ayuda a rastrear dónde la lógica se desvió de sus expectativas. También puedes analizar cómo se construye el contexto a lo largo de varios giros de conversación, observando cómo el flujo de trabajo evoluciona de forma natural. Más allá de la depuración, la trayectoria sirve como documentación, lo que le permite capturar ejemplos de comportamiento correcto que pueden compartirse con los miembros del equipo o utilizarse como casos de referencia para desarrollos futuros. Esta vista es particularmente valiosa para los equipos que construyen con IA generativa que necesitan validar la adaptabilidad de los agentes en diversos escenarios.

Vamos a repasar la trayectoria del agente meteorológico que se muestra en la captura de pantalla:

1. La consulta del usuario

La conversación comienza con una solicitud clara y específica sobre el clima en la ciudad de Nueva York.

2.   El agente realiza una llamada a la herramienta

El agente reconoce que necesita datos externos e invoca la herramienta meteorológica:

Este ejemplo muestra que el agente identificó correctamente las coordenadas aproximadas de NYC, estructuró adecuadamente la solicitud de la API y estableció la señal apropiada para el clima actual.

IBM Telemetry muestra este resultado como JSON sin procesar y como una vista de árbol ampliable y bien analizada.

3. La herramienta devuelve datos

La API meteorológica responde con datos meteorológicos estructurados:

Este ejemplo muestra que la herramienta recuperó correctamente los datos y la respuesta sigue el esquema esperado y todos los campos obligatorios están presentes. Ser capaz de inspeccionar la respuesta de la herramienta sin procesar es crucial para problemas de depuración en los que el agente malinterpreta los resultados de la herramienta.

4. El agente resume el resultado

Finalmente, el agente procesa los datos estructurados y responde de forma natural:

El agente extrajo correctamente el código de temperatura y clima, y convirtió los datos estructurados en lenguaje natural. La respuesta es concisa y responde a la pregunta del usuario.

La pestaña Trayectoria también permite filtrar por rol para ver solo mensajes de usuario, mensajes de agentes o interacciones con herramientas. También puedes expandir y contraer partes de conversaciones largas para enfocarse en detalles que le importan. Para un mayor análisis o depuración, puede exportar los datos como JSON para pasar a tareas vinculadas desde pasos de trayectoria para obtener los detalles correspondientes.

¡Felicitaciones! Configuró correctamente IBM Telemetry con watsonx Orchestrate y aprendió a monitorear y analizar en profundidad el comportamiento de los agentes de IA. IBM Telemetry proporciona múltiples capas de visibilidad para brindarle una observabilidad completa de cómo piensan, deciden y actúan sus agentes de IA. Estas capacidades que ha explorado son cruciales para la gestión efectiva del ciclo de vida de las operaciones de los agentes en producción o para la integración con otros entornos de agentes en su entorno.

Si tiene problemas o preguntas, consulte la documentación. Los problemas más comunes se tratan en la guía de resolución de problemas. También puede revisar los problemas de GitHub para ver si otros usuarios han experimentado problemas similares.

El monitoreo de agentes a través de plataformas como IBM Telemetry ha creado un ecosistema sólido para AgentOps, que se vuelve esencial a medida que los agentes autónomos asumen tareas más complejas que implican la integración de SDK, herramientas y API externas. La visibilidad que adquirió sobre el comportamiento de los agentes permite crear sistemas de IA más confiables y eficientes.