AgentOps: monitorice y gobierne los agentes de IA con IBM Telemetry utilizando 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 fiabilidad y el gobierno. AgentOps, la práctica de monitorizar, observar y gestionar agentes de IA en producción, proporciona la visibilidad necesaria para construir sistemas de IA agéntica fiables.

Este tutorial proporciona una guía paso a paso para configurar y utilizar IBM Telemetry con watsonx Orchestrate Developer Edition para monitorizar y gobernar agentes de IA. Aprenderá cómo habilitar la observabilidad de los agentes de IA y analizar su comportamiento en profundidad, desde llamadas individuales a 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 de los agentes
• Importar y probar un agente de IA preconfigurado con integración de herramientas externas
• Analizar el comportamiento de los agentes mediante rastreos, tareas, intervalos y flujos de trabajo detallados
• Depure problemas y optimice el rendimiento del agente mediante el uso de análisis.

IBM Telemetry es el marco de observabilidad nativo de watsonx Orchestrate que captura información detallada sobre cómo sus 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, puede realizar un seguimiento de las métricas de rendimiento, monitorizar el coste de LLM, identificar errores y asegurarse de que sus agentes funcionan 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 o superior (Consúltelo 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 del ADK.

• WatsonX Orchestrate ofrece una prueba gratuita de 30 días si no tiene una cuenta.
• watsonx Orchestrate API Key, generada desde su panel de control de IBM Cloud

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

Para empezar, clona el repositorio de GitHub usando https://github.com/IBM/ibmdotcom-tutorials.git como URL HTTPS. Para obtener 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 de proyecto de este tutorial:  wxo-agentops. Este directorio es donde trabajará a medida que lo siga.

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

Para usar el ADK, debe conectarlo a un entorno Watsonx Orchestrate existente. Si aún no tiene una cuenta 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 el ADK.

Estos pasos lo guiarán durante la instalación mediante un entorno virtual de Python, que es el enfoque recomendado para mantener aisladas las dependencias. Para obtener métodos de instalación alternativos e instrucciones detalladas, consulte la documentación "Primeros pasos con ADK".

Cree un nuevo entorno virtual en 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 de su terminal debería cambiar para indicar que está trabajando dentro del entorno virtual (normalmente mostrando (.venv ) al principio de la instrucción).

Una vez activado su entorno virtual, instale el ADK mediante pip:

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

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

El ADK utiliza un archivo .env  para autenticar sus credenciales de usuario y configurar watsonx Orchestrate Developer Edition. Las variables de entorno que necesita 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 empezar.

Para ver los métodos de autenticación alternativos y las instrucciones de configuración detalladas, consulte la documentación del archivo de configuración de su entorno.

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

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

• WO_INSTANCE : esta URL es su instancia de watsonx Orchestrate. Puede encontrar esta información en la información de registro de su cuenta de watsonx Orchestrate y navegando a los datos de su instancia. Haga clic en el icono de su perfil > Configuración y, a continuación, seleccione la pestaña Detalles de la API. Para instrucciones detalladas sobre cómo empezar con la API, consulta la documentación de Watsonx Orchestrate.

La URL sigue este formato:

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

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

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

Ahora está listo para instalar la 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 da acceso inmediato a las características de observabilidad.

Comprender el comando de instalación

El ADK proporciona un único comando que gestiona 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> : apunta a su archivo de configuración que contiene credenciales
• --with-ibm-telemetry : permite el marco de observabilidad nativo de IBM Telemetry

Ejecute el comando desde su 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> . Añadir el indicador --with-ibm-telemetry  permite 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 el ADK para:

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

El 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 correcta produce un output similar al de este ejemplo:

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

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

1.    Reiniciar 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 registros del servidor:

Puede ver los registros de servicio del servidor de 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 vuelva a instalar.

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.). Debe activar explícitamente el entorno local que ha creado:

Debería recibir la 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 IU de chat de watsonx Orchestrate con el siguiente comando:

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

La interfaz de chat proporciona una forma sencilla 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 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. Es el resultado esperado; en el siguiente paso añadirá su primer agente.

Ahora que su entorno está configurado, es el momento de importar un agente de IA preconfigurado que demuestre las capacidades de monitorización de IBM Telemetry. Este agente meteorológico utiliza una herramienta API externa para obtener datos meteorológicos en tiempo real, ofreciéndole un ejemplo práctico para observar y analizar.

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

• Demuestra el uso de la herramienta: muestra cómo los agentes llaman a las API externas.
• Proporciona un comportamiento claro y observable: cada petición sigue un patrón predecible
• Genera datos de telemetría significativos: genera registros detallados que puede analizar en IBM Telemetry
• Incluye escenarios de error: le ayuda a entender cómo la telemetría gestiona los fallos
• Ilustra la automatización: elimina la búsqueda manual de datos mediante las acciones del agente

Desde la raíz de su proyecto (wxo-agentops ), navegue hasta la carpeta Weather Agent:

Este directorio contiene dos archivos de configuración YAML:

• get_weather.yaml : define la herramienta 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 ha importado correctamente.

Ahora importe el agente que utilizará esta herramienta:

Este comando registra Weather Agent 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 en ubicaciones no válidas

Vuelva a su 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 situado en la parte superior de la interfaz de chat) y seleccione Weather_Agent de la lista

Con el Weather Agent seleccionado, intente hacer algunas preguntas para generar datos de telemetría:

Consultas de ejemplo:

• “¿Qué tiempo hace en la ciudad de Nueva York?”
• "¿Puedes decirme la temperatura actual en Londres?"
• "¿Qué tiempo hace en Tokio?"
• "¿Está lloviendo en Seattle ahora mismo?"

El agente procesará cada solicitud de la siguiente manera:

1. Entendiendo 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 Weather Agent. El sistema está registrando:

• El contexto completo de la conversación
• Cada invocación de LLM y los tokens utilizados
• Llamadas a herramientas con sus entradas y outputs
• Decisiones de enrutamiento y pasos del flujo de trabajo
• Tiempos de ejecución y métricas de rendimiento
• Cualquier error o excepción que se produzca
• Interacciones con proveedores externos y sus tiempos de respuesta

En los próximos pasos, explorará estos datos de telemetría en detalle para entender exactamente cómo se comporta su agente.

Ahora viene la parte más potente de este tutorial: utilizar IBM Telemetry para obtener una visibilidad profunda del comportamiento de su agente. IBM Telemetry ofrece múltiples vistas y herramientas de análisis que le permiten entender todos los aspectos de cómo su agente procesa las solicitudes.

Abra su navegador y navegue hasta https://localhost:8765/?serviceName=wxo-server. La interfaz proporciona reproducciones de sesión que permiten revisar las interacciones anteriores de los agentes para analizarlas.

Nota: La URL usa https pero como este espacio es un entorno de desarrollo local, es posible que su navegador muestre una advertencia de seguridad sobre un certificado autofirmado. Se espera este mensaje y es seguro pasar en su entorno local.

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

Accederá al panel de control principal de IBM Telemetry.

El panel de control 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 del panel de rastreo y selección de grupos para ver análisis detallados sobre su última charla con el agente meteorológico.

Este paso le lleva a la pantalla de Agent Analytics, que sirve como centro para entender el comportamiento de los agentes.

La pantalla Agent Analytics ofrece una visión general del seguimiento seleccionado, que incluye:

• Estadísticas resumidas: tiempo total de ejecución, uso de tokens, estimaciones de costes y datos de evaluación comparativa.
• Información del agente: qué agente tramitó 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 proporciona perspectivas inmediatas sobre si el agente funcionó como se esperaba y con qué eficacia operó.

La sección de Tareas es donde dedicará la mayor parte del tiempo a analizar el comportamiento de los agentes. Proporciona un cronograma visual paso a paso de todo lo que el agente hizo durante una solicitud (cada llamada de LLM, cada invocación de herramientas, cada decisión de enrutamiento y cada output).

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. Su rastreo de Weather Agent debería mostrar una estructura similar a este ejemplo:

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

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

Este enfoque es importante porque la duración de la tarea raíz indica la latencia total que ha experimentado 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 gestionar el mensaje y clasifica la solicitud según un estilo de gestión. El router analiza la solicitud entrante y decide si requiere manejo conversacional, ejecución guiada por herramientas, generación aumentada por recuperación (RAG) o orquestación multiagente.

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

• 0.1:agent El contexto principal de ejecución del agente que orquesta toda la solicitud. Esta tarea recopila la instrucción a partir de las interacciones del sistema, el historial de conversaciones y las respuestas de las herramientas. Aplica reglas y políticas de orquestación y prepara las entradas para el LLM. Esta tarea determina qué tipo de llamada 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 mediante llamadas estructuradas a herramientas.

Este paso es el paso de "pensamiento" en el que 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 caro, este paso suele ser la causa principal.

• 0.2:answer : el paso final de la cadena toma el output del LLM y lo formatea para su entrega. Esta tarea convierte el output del LLM en el formato de respuesta final y aplica cualquier regla de postprocesamiento o formato. Por último, devuelve la respuesta a la interfaz de chat.

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

Resumen del flujo de trabajo de tareas

Para resumir el flujo de trabajo completo:

1. El router decide cómo manejar la petición
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. Formatea la respuesta y devuelve el output final

Todo este flujo de trabajo está incluido en el contenedor de solicitudes  ROOT, que le da 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, estado interno.

Ejemplo: Para la tarea WatsonxChatModel.chat , los atributos de entrada incluirían el prompt completamente ensamblado con instrucciones del sistema, historial de conversaciones y cualquier resultado de la herramienta que necesite ser interpretado.

2.    Atributos de output: muestran el resultado de la tarea, incluyendo: las completaciones del LLM, las llamadas a herramientas y las decisiones.

Ejemplo: La misma tarea WatsonxChatModel.chat  puede generar un output en lenguaje natural o una llamada estructurada a una herramienta como get_weather(latitude=40, longitude=-74).

3.    Atributos generales: proporcione metadatos de telemetría: uso de tokens, información temporal, identificadores como identificadores únicos e información sobre el modelo.

Ejemplo: Podría ver que una tarea usaba 450 tokens de entrada y 120 tokens de output, tardaba 1,2 segundos en ejecutarse y usaba el ibm/granite-3.1-8b-instruct model.

Cómo utilizar los atributos de las tareas

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

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

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

Las métricas clave incluyen:

• Tiempo total de ejecución: cuánto tiempo duró la tarea de principio a fin
• Número de llamadas en el LLM: cuántas veces se invocó el modelo de lenguaje
• Recuento de llamadas a herramientas: cuántas veces se llamó a herramientas externas
• Uso de tokens: tokens de entrada, tokens de output y total de tokens consumidos
• Estimaciones de costes: los costes aproximados se basan en el uso de los tokens (cuando los datos de precios estén disponibles)
• Distribución de subtareas: cómo se distribuía el trabajo entre las tareas secundarias

Estas métricas le ayudan a optimizar el rendimiento y a depurar el comportamiento de los agentes. También pueden ayudar a identificar tareas lentas que podrían paralelizarse o almacenarse en caché. Esta vista es integral para la planificación de la capacidad porque le permite comprender los requisitos de 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 se dedicaron 0,5 segundos a las llamadas al LLM, sabrá que el cuello de botella se encuentra en otra parte (probablemente en la ejecución de la herramienta o en la latencia de la red).

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

Los spans 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 wxo-server). 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 preparada (WatsonxChatModel.chat)
• Devolver los resultados al usuario (answer.task)

Mientras que las tareas muestran los pasos lógicos de la ejecución del agente (lo que el agente intenta lograr), los intervalos muestran los pasos técnicos (cómo lo lleva a cabo el sistema). Esta doble perspectiva le proporciona tanto una visión general como la capacidad de depuración detallada.

Ejemplo: Una sola tarea como 0.1:agent puede contener varios intervalos que representan consultas a bases de datos, búsquedas de caché y carga de configuración. Estas operaciones se producen entre bastidores para respaldar 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.

Entre las etiquetas de span más comunes se 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 spans resultan útiles para localizar la latencia, comprender los fallos al identificar qué componente interno ha fallado, analizar patrones filtrando los spans por etiqueta para identificar tendencias y realizar referencias cruzadas vinculando spans de múltiples trazas mediante el uso de identificadores de sesión.

Por ejemplo, si su agente se bloquea de vez en cuando, puede filtrar los intervalos por duración para identificar qué operaciones internas están tardando más de lo esperado, como 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 ejecutable, que muestra la estructura de ejecución completa del flujo de trabajo de su agente. Esta vista es especialmente útil para comprender sistemas multiagente complejos y patrones de ejecución anidados.

En el marco watsonx Orchestrate, un runnable es una unidad de trabajo o tarea que puede ejecutarse. Los objetos runnable pueden ser:

• Operaciones sencillas: una sola llamada de LLM o invocación de herramienta
• Flujos de trabajo compuestos: varios elementos ejecutables encadenados entre sí
• Sucursales condicionales: diferentes rutas de ejecución según las condiciones
• Ejecuciones paralelas: varios runnables que se ejecutan simultáneamente

El "Runnable Tree" muestra las relaciones entre elementos principales y secundarios, lo que facilita la visualización de:

• Qué tareas desencadenan otras: seguimiento de la cadena de ejecución
• Ejecución paralela vs. secuencial: comprensión de la concurrencia del flujo de trabajo
• Lógica de ramificación: cómo las decisiones conducen a diferentes rutas de ejecución
• Profundidad del flujo de trabajo: el nivel de anidamiento de la lógica de su agente

Para agentes simples como Weather Agent, la vista de flujo de trabajo refleja fielmente la vista de tareas. Sin embargo, los flujos de trabajo resultan de gran utilidad cuando se trabaja con:

• Sistemas multiagente: múltiples agentes especializados colaborando 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 basados en resultados intermedios
• Arquitecturas escalables: diseño de flujos de trabajo que gestionen las cargas del mundo real de forma eficiente

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

Puede interactuar con el árbol de la siguiente manera:

• Nodos que se expanden/colapsan: concéntrese en secciones específicas del flujo de trabajo
• Hacer clic en los nodos: ir a la información detallada de las tareas
• Seguir las rutas de ejecución: rastrear cómo fluyen los datos por la ventana
• Identificación de cuellos de botella: detectar dónde los flujos de trabajo se vuelven ineficientes

La visualización hace que depurar los flujos de trabajo sea mucho más fácil que intentar seguir los registros de texto o rastrear los datos por sí solo.

La pestaña Eval (evaluación) proporciona una vista de control y garantía de calidad que mide la corrección y la fiabilidad de la ejecución de su agente. En este paso se pasa de observar lo que ha ocurrido a evaluar cómo se ha desarrollado.

La pestaña Eval muestra los resultados de la evaluación que evalúan la calidad a través de medidas de seguridad:

• Éxito de la tarea: Qué tareas se completaron y cuáles fallaron
• Calidad de output: Si los resultados coincidían con los resultados esperados 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 los fallos
• Validación de casos de uso: Si el comportamiento de los agentes coincide con los casos de uso previstos

Las evaluaciones le ayudan a monitorizar la fiabilidad al realizar un seguimiento de la coherencia con la que su agente produce resultados correctos, identificar cuándo los cambios degradan el rendimiento del agente, priorizar las mejoras y generar confianza validando que los agentes funcionan correctamente antes de la implementación en producción.

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

Si observa que el 15 % de las consultas meteorológicas no se evalúan, puede investigar esos rastros específicos para comprender si el problema es una mala gestión de las entradas, fallos de la API o un formato de respuesta incorrecto.

La pestaña Issues ofrece una vista centralizada de todo lo que salió mal durante la ejecución del flujo de trabajo. Esta pestaña es su primera parada a la hora de depurar fallos o comportamientos inesperados del agente.

La pestaña Issues enumera problemas como:

• Llamadas fallidas a la API: servicios externos que devolven errores
• Fallos en la ejecución de herramientas: herramientas que se bloqueaban o se agotaban
• Faltan entradas: los datos requeridos no están disponibles cuando son necesarios
• Excepciones modelo: errores de 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 superaron los límites de tiempo
• Fallos de tiempo de ejecución no controlados: 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 de problemas muestra:

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

Este enfoque facilita la comprensión de lo que salió mal sin tener que buscar en los registros o en los datos de rastreo.

La pestaña Issues es especialmente valiosa porque agrega fallos en lugar de obligarle a buscar entre tareas individuales. Proporciona un contexto completo al incluir todos los detalles del error y los datos relacionados, mientras que los niveles de gravedad permiten una clasificación rápida para que pueda priorizar los problemas que se deben abordar primero. Los enlaces directos a las tareas de origen permiten que, con un solo clic, se acceda al punto exacto de ejecución en el que se produjo el error.

La pestaña Trajectory ofrece una vista cronológica tipo conversación de la interacción del agente entre el usuario y cualquier herramienta que el agente invoque. Esta perspectiva resulta inestimable para comprender el contexto completo y la evolución del comportamiento de los agentes.

La vista de trayectoria es útil porque le 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 las herramientas asegurándose de que se invocan con los parámetros correctos y de que reciben las respuestas adecuadas. Al depurar respuestas inesperadas, la trayectoria le ayuda a rastrear dónde la lógica divergió de sus expectativas. También puede 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, permitiéndote capturar ejemplos de comportamiento correcto que pueden compartirse con miembros del equipo o usarse como casos de referencia para futuros desarrollos. Esta visión es especialmente valiosa para equipos que construyen con IA generativa y que necesitan validar la adaptabilidad de los agentes en escenarios diversos.

Repasemos 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 tiempo en la ciudad de Nueva York.

2.    El agente realiza una llamada a una 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 Nueva York, estructuró adecuadamente la solicitud para la API y estableció el indicador correspondiente al tiempo actual.

IBM Telemetry muestra este resultado tanto en formato JSON sin procesar como en una vista de árbol bien estructurada y expandible.

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. Poder examinar la respuesta sin procesar de la herramienta es fundamental para solucionar los problemas en los que el agente interpreta erróneamente los outputs de la herramienta.

4.    El agente resume el resultado

Por último, el agente procesa los datos estructurados y responde de forma natural:

El agente ha extraído correctamente el código de temperatura y tiempo y ha convertido los datos estructurados en lenguaje natural. La respuesta es concisa y responde a la pregunta del usuario.

La pestaña Trajectory también permite filtrar por función para ver solo los mensajes de los usuarios, los mensajes de los agentes o las interacciones de las herramientas. También puede ampliar y condensar partes de largas conversaciones para centrarse en detalles que le importan. Para un análisis o depuración más detallados, puede exportar los datos como JSON para saltar a las tareas vinculadas desde los pasos de la trayectoria para obtener los detalles correspondientes.

¡Enhorabuena! Ha configurado correctamente IBM Telemetry con watsonx Orchestrate y ha aprendido a monitorizar y analizar en profundidad el comportamiento de los agentes de IA. IBM Telemetry proporciona múltiples capas de visibilidad para darle una observabilidad completa sobre cómo piensan, deciden y actúan sus agentes de IA. Estas capacidades que ha explorado son cruciales para una gestión eficaz del ciclo de vida de las operaciones de agentes en producción o para integrarlas con otros marcos 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 solución de problemas. También puede consultar las reseñas de GitHub para ver si otros han experimentado problemas similares.

La monitorización de agentes a través de plataformas como IBM Telemetry ha creado un ecosistema sólido para AgentOps, convirtiéndose en 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 ha adquirido sobre el comportamiento de los agentes le permite crear sistemas de IA más fiables, eficientes y de IA fiable.