A medida que el número de agentes de IA creados aumenta a diario, las empresas están explorando sistemas autónomos para la toma de decisiones y los flujos de trabajo operativos. Al mismo tiempo, las organizaciones suelen expresar su preocupación por la explicabilidad, la gobernanza y la preparación para la producción, especialmente en los sistemas multiagente que dependen de modelos de lenguaje grandes (LLM) para el razonamiento. Es un desafío utilizar agentes en entornos de negocios que proporcionen respuestas sin una explicación clara o que exhiban un comportamiento incongruente.
Estos desafíos pueden abordarse mediante el uso de IBM® watsonx Orchestrate que proporciona una plataforma estructurada, que admite autoalojamiento, razonamiento basado en herramientas, llamadas a API y control de nivel empresarial sin requerir código de orquestación personalizado.
Dynamiq creó un asistente de investigación legal multiagente para un importante cliente de seguros, enrutando las consultas a través de un clasificador IBM Granite de bajo costo antes de escalar a un agente de investigación más complejo. Hacer viable este flujo de trabajo de alto riesgo requería una visibilidad profunda de cada paso de razonamiento y llamada a la herramienta. Al integrar IBM watsonx Orchestrate, Dynamiq garantizó que cada decisión siguiera siendo totalmente rastreable, auditable y citada, reduciendo el tiempo de revisión de contratos de 90 minutos a 45 sin sacrificar la gobernanza.
En este tutorial, aprenderá a crear un agente de IA en watsonx Orchestrate con watsonx Orchestrate Agent Development Kit (ADK). En sistemas de IA basados en LangChain o LangGraph, los desarrolladores suelen gestionar manualmente los reintentos, la gestión de estados y la ejecución asincrónica. Watsonx Orchestrate ADK facilita este proceso mediante la gestión integrada del ciclo de vida que permite despliegues de agentes coherentes y listos para la empresa.
Utilizará Python para crear la lógica de evaluación de riesgos, definir el comportamiento del agente e incorporar Langfuse para monitorear y mejorar el comportamiento del agente con rastreos de ejecución reales. También puede encontrar este tutorial en GitHub.
Langfuse es una plataforma de observabilidad de LLM de código abierto construida sobre OpenTelemetry para monitorear aplicaciones y agentes de LLM. Utiliza telemetría (rastreos, métricas y registros) para monitorear los rastreos de las ejecuciones de agentes, incluidas las llamadas a LLM y a herramientas, el uso de tokens, los metadatos y la latencia a nivel de solicitud y por sesión.
Permite a los desarrolladores obtener insights profundos sobre el rendimiento de los agentes en escenarios del mundo real, identificar las causas principales de los resultados incorrectos y optimizar sistemáticamente el comportamiento de los agentes para una mayor confiabilidad y eficiencia.
El objetivo de este tutorial es crear un agente de IA para la gobernanza empresarial que evalúe el riesgo de los proveedores a través de un análisis determinista basado en reglas. Creamos un conjunto de datos sintético de proveedores con calificaciones financieras, certificaciones de seguridad e historial de incidentes. El agente procesa estos datos y clasifica a los proveedores en niveles de riesgo específicos (bajo, medio o alto), al tiempo que proporciona justificaciones de sus decisiones.
También admite seguimientos interactivos que permiten a los usuarios comparar proveedores o simular cómo los cambios en los datos afectarían a una puntuación de riesgo, asegurando el alto nivel de auditabilidad necesario para el cumplimiento corporativo.
A continuación se muestra una demostración interactiva del agente de riesgo de proveedor completo creado en este tutorial. Explore cómo el agente clasifica a los proveedores, responde a las preguntas y rastrea su razonamiento a través de Langfuse, para que tenga una idea clara de lo que está construyendo antes de comenzar.
Para completar este tutorial, necesita:
Python 3.11 o posterior instalado en su sistema.
Una cuenta de watsonx Orchestrate. Para este tutorial, una cuenta de prueba es suficiente. Puede utilizar IBM Cloud para crear una prueba gratuita de 30 días cuando no tenga una cuenta.
Una clave de API de watsonx Orchestrate desde la interfaz de usuario (IU) de Orchestrate.
Un watsonx Orchestrate ADK instalado en su sistema.
Inicie sesión en watsonx Orchestrate a través de IBM Cloud y abra la interfaz de usuario (IU) de watsonx Orchestrate. Vaya a los detalles de la API después de abrir Configuración en el menú del perfil. Cree una nueva clave de API, cópiela y guárdela de forma segura. Durante el desarrollo local, watsonx Orchestrate ADK se autentica con esta clave de API. Watsonx Orchestrate actúa como un SDK (kit de desarrollo de software) local para crear y probar la lógica del agente.
En este paso, cree un entorno de desarrollo local. A lo largo de este tutorial, ejecutará un servidor de desarrollo local, importará herramientas, configurará entornos y creará agentes a través de la interfaz de línea de comandos (CLI) orquestada, proporcionada por el ADK en Powershell. Comience por navegar hasta el directorio donde desea construir su proyecto. A continuación, cree un nuevo entorno virtual Python:
Se crea un entorno Python aislado en una carpeta .venv . El uso de un entorno virtual garantiza que todas las dependencias de este tutorial estén separadas de la instalación de Python en todo su sistema.
Luego, active el entorno virtual. El sistema operativo determina qué comando de activación se va a utilizar.
En Windows:
macOS y Linux:
Una vez activado, la instrucción del terminal mostrará .venv al principio para indicar que está trabajando en un entorno virtual.
Con el entorno virtual activo, instale watsonx Orchestrate ADK en su máquina local. Para usar ADK, conéctelo a su entorno watsonx Orchestrate existente. Ejecute el siguiente comando en PowerShell:
Puede seguir estos pasos de la instalación de ADK según los pasos del documento oficial de instalación.
Nota: Este tutorial ejecuta el tiempo de ejecución de watsonx Orchestrate Developer Edition localmente y lo conecta a la instancia SaaS de watsonx Orchestrate con las credenciales.
Para ejecutar este método, cree un archivo llamado .env en la raíz de la carpeta del proyecto y agregue los siguientes valores:
Este archivo .env es necesario para ejecutar el servidor. En los siguientes pasos, lo iniciará con el comando orchestrate server start -e .env -l.
A continuación, debe configurar su ADK con una clave de API de watsonx Orchestrate válida para conectar su entorno local a watsonx Orchestrate.
Nota: ADK Watsonx Orchestrate es compatible con múltiples tipos de entornos, incluyendo IBM Cloud, AWS y despliegues on premises. En este tutorial, utilizamos el entorno on-prem y nos autenticamos con una clave de API a través de la CLI de ADK. ADK gestiona de forma segura las credenciales internamente, por lo que no se implementa ninguna configuración manual de variables de entorno para esta configuración.
Desde el directorio de su proyecto (con el entorno virtual activado), ejecute el siguiente comando para agregar su entorno watsonx Orchestrate:
Aquí, service-instance-url es la URL de su instancia watsonx Orchestrate. Puede encontrar esta información en la misma pestaña Detalles de la API en Configuración en la IU de watsonx Orchestrate.
A continuación, active el entorno que agregó:
Ahora, cuando se le solicite, ingrese la clave de watsonx Orchestrate obtenida en el paso 1. Cuando se haya activado el entorno, cualquier comando posterior relacionado con ADK, como la importación de agentes, las herramientas o la ejecución del servidor, se ejecutará en el entorno de watsonx Orchestrate.
Nota: Si desea ejecutar todo localmente con Developer Edition, puede activar el entorno local predeterminado a través de:
Esto cambia su ADK al entorno local integrado de Orchestrate, que es útil para las pruebas locales.
En este paso, creará la plantilla de marco de agente que contiene la definición, las herramientas y el código fuente de su Agente de inteligencia de riesgos de proveedor. Luego, cree la estructura de carpetas necesaria para el desarrollo local basado en ADK:
Puede agregar el comando dado aquí para crear la estructura del agente:
Cada carpeta tiene un propósito específico:
La carpeta agents contiene el archivo YAML con las instrucciones, reglas de razonamiento y configuración del modelo agent. Determina cómo el sistema responde a las preguntas de los usuarios. La carpeta tools contiene un archivo YAML que describe la herramienta proporcionada al agente. La carpeta src contiene la implementación de Python para herramientas personalizadas y lógica de negocios.
Inicie el servidor watsonx Orchestrate para que pueda recibir y almacenar sus importaciones antes de importar herramientas y agentes. Ejecute este comando desde la raíz de la carpeta del proyecto:
El siguiente paso es la observabilidad del agente, donde se analiza cómo se comporta el agente en tiempo de ejecución, por ejemplo, qué herramientas se llaman, la latencia y dónde se producen los errores. Para ello, active la observabilidad de Langfuse en el entorno watsonx Orchestrate ADK.
En este tutorial, se utiliza la versión Langfuse SaaS, que le permite capturar rastreos sin ejecutar Langfuse localmente.
Asegúrese de que el servidor watsonx Orchestrate se esté ejecutando (paso 6) antes de configurar Langfuse.
Después, cree una cuenta de Langfuse en https://cloud.langfuse.com. Después de iniciar sesión, cree una nueva organización y proyecto. Desde la configuración del proyecto, copie su ID de proyecto, su clave pública, su clave secreta y su URL de host.
Ahora configure Langfuse en watsonx Orchestrate ADK con el comando que se muestra después de esta sección y reemplace los marcadores de posición con los valores copiados:
Una vez que este comando haya finalizado correctamente, el módulo Langfuse se integrará completamente en el entorno de watsonx Orchestrate. En esta etapa, todas las interacciones con los agentes se registran automáticamente en el módulo Langfuse.
Ahora que el servidor se está ejecutando, puede probar el agente.
El siguiente paso es definir el agente de inteligencia de riesgos del proveedor. Los agentes en watsonx Orchestrate ADK se declaran con archivos YAML que describen el objetivo del agente, las limitaciones de razonamiento, la configuración del modelo y las herramientas permitidas.
Dentro del directorio agents, cree un archivo llamado vendor-risk-agent.yaml. Este archivo es la capa de gestión de instrucciones del agente que garantiza que todas las respuestas se basen en un razonamiento determinista en lugar de una inferencia de forma libre.
La definición de agente utilizada en este tutorial se muestra a continuación. Copie y pegue la siguiente definición de agente en su archivo agents/vendor-risk-agent.yaml. Guarde el archivo después.
Esta configuración garantiza que el agente se comporte de forma previsible en cuanto a qué, por qué, cómo y preguntas de comparación. El sistema evita las alucinaciones al prohibir las suposiciones sobre calificaciones financieras o significados de riesgo a menos que los resultados de la herramienta los definan explícitamente.
En este paso, implemente la herramienta Python que realiza la evaluación de riesgos del proveedor. En watsonx Orchestrate ADK, la lógica de negocio personalizada se implementa mediante herramientas Python que hacen que los agentes comiencen a obtener los resultados. En lugar de depender del ajuste de un modelo para un comportamiento específico del dominio, este tutorial demuestra cómo se puede implementar el razonamiento determinista basado en reglas a través de las herramientas de Python para garantizar resultados coherentes.
Dentro de la carpeta src, cree un archivo llamado main.py. Este archivo contiene el conjunto de datos del proveedor que creamos, las reglas de evaluación de riesgos y una herramienta Python llamada evaluate_all_vendor_risk que proporciona la lógica al agente.
La lógica de riesgo se basa en reglas. En términos de señales de alto riesgo, una empresa puede recibir una puntuación de riesgo debido a su bajo rendimiento, incidentes de seguridad en el pasado o consultas regulatorias. Una empresa puede recibir una puntuación de riesgo media debido a la ausencia de certificaciones, incidentes operativos únicos o interrupciones por condiciones climáticas.
La función evaluate_all_vendor_risks se hace como una herramienta de watsonx Orchestrate, por lo que el agente puede llamarla durante la ejecución. La herramienta devuelve una salida estructurada que incluye el nivel de riesgo final junto con las razones exactas que causaron la clasificación.
Nota: El archivo main.py incluido en este tutorial es la versión final actualizada de la lógica de evaluación de riesgos del proveedor. Los primeros conjuntos de código causaron comportamientos erróneos de los agentes, que se analizaron a través de rastreos de Langfuse. Puede encontrar los rastreos de Langfuse en las capturas de pantalla que se proporcionan en los pasos posteriores de este tutorial.
La implementación completa del archivo main.py utilizado en este tutorial se proporciona a continuación. Cópielo y péguelo en src/main.py. Después de eso, guarde el archivo.
En este paso, la herramienta y el agente deben estar disponibles para watsonx Orchestrate. Este proceso se realiza importando estos componentes al entorno ADK activado. Antes de ejecutar los comandos de importación, asegúrese de estar dentro de la carpeta raíz de su proyecto (la misma carpeta que contiene los directorios de agents, src y tools).
En primer lugar, importe la herramienta Python para que watsonx Orchestrate pueda registrarla como capacidad ejecutable. Desde la raíz del directorio de su proyecto, ejecute el siguiente comando:
Este comando empaqueta el código Python en un módulo, registra la herramienta evaluate_all_vendor_risks y permite que los agentes la llamen.
Luego, el Agente de inteligencia de riesgos del proveedor se integra completamente con la herramienta Python en el entorno de watsonx Orchestrate.
Con el servidor local de watsonx Orchestrate en ejecución y la observabilidad del agente habilitada, ahora puede probar el agente y analizar su comportamiento en tiempo real.
Inicie la interfaz de chat ejecutando el siguiente comando:
Ahora abra la IU del chat de watsonx Orchestrate en su navegador. Desde el selector de agentes, elija Vendor_Risk_Intelligence_Agent y comience a hacer preguntas relacionadas con el riesgo de los proveedores.
Para verificar que el agente responde correctamente (y llama a la herramienta Python de manera determinista), estas son algunas preguntas de muestra que puede usar para las pruebas:
A medida que interactúa con el agente, abra el panel de Langfuse en su navegador. Cada consulta de usuario crea un nuevo seguimiento, incluye un identificador de sesión y un ID de usuario. Estos rastreos registran la ruta de ejecución completa del agente. Al seleccionar un rastreo, puede analizar:
La entrada y salida completas del agente
La invocación de la herramienta Python
Los datos estructurados devueltos por la herramienta
El proceso de razonamiento seguido para llegar a la respuesta final
Latencia para cada paso del proceso
Flujo de conversación basado en sesiones para múltiples preguntas
Esta observabilidad ayuda a analizar las métricas de rendimiento que señalan cuellos de botella como errores en la suposición, reglas incompletas o comportamientos inesperados de los agentes.
Después de probar el agente, utilice los rastreos de Langfuse para identificar las respuestas incorrectas. Langfuse muestra cada invocación de herramienta, paso de razonamiento y latencia de respuesta, lo que facilita la comprensión de por qué se produjo una respuesta.
En este caso de uso, el análisis de rastreo reveló que se produjeron algunas respuestas incorrectas cuando el agente infirió significados financieros o respondió sin citar explícitamente pruebas basadas en reglas. Para cambiar esta acción, se modificaron las instrucciones del agente y el código Python correspondiente para arreglar el pensamiento estricto basado en reglas con la acción de herramienta requerida.
Después de volver a importar los archivos actualizados, se volvió a probar el agente. Los nuevos rastreos garantizan que las respuestas estuvieran firmemente arraigadas en los resultados estructurados de la herramienta, que las explicaciones fueran deterministas y que las respuestas a todas las preguntas descriptivas fueran correctas.
Este proceso de observación y refinamiento muestra cómo Langfuse ayuda al desarrollo seguro y sólido de los agentes en función del feedback de los usuarios.
Explore la demostración interactiva a continuación para conocer el agente de riesgo del proveedor y el rastreo de Langfuse en acción.
Este tutorial lo guio a través de la creación de un agente de IA estructurado y confiable con watsonx Orchestrate que está desarrollado para la creación de agentes de nivel empresarial. Con la integración de instrucciones lógicas y claras de agentes de Python basadas en reglas sencillas y herramientas reutilizables, implementó un caso de uso en la evaluación de riesgos del proveedor con código mínimo y máxima transparencia.
La incorporación de Langfuse facilitó la detección del comportamiento de los agentes y la identificación de los problemas con razonamiento para mejorar continuamente la precisión sin conjeturas. Este enfoque ayuda a las empresas a optimizar los sistemas de agentes de principio a fin, automatizar flujos de trabajo complejos y desplegar sistemas de IA con total transparencia.
Más importante aún, juntos, watsonx Orchestrate ADK y Langfuse permiten a las empresas diseñar, depurar y escalar flujos de trabajo de agentes complejos y aplicaciones de IA más rápido, con una gobernanza más sólida y un razonamiento más claro y un tiempo de desarrollo reducido.
Cree, implemente y gestione poderosos asistentes y agentes de IA que automaticen flujos de trabajo y procesos con IA generativa.
Construya el futuro de su empresa con soluciones de IA en las que pueda confiar.
Los servicios de IA de IBM Consulting ayudan a reinventar la forma en que las empresas trabajan con IA para la transformación.