A medida que el número de agentes de IA creados crece a diario, las empresas exploran sistemas autónomos para apoyar la toma de decisiones y los flujos de trabajo operativos. Al mismo tiempo, las organizaciones suelen expresar su preocupación por la explicabilidad, el gobierno y la preparación para la producción, especialmente en los sistemas multiagente que se basan en modelos lingüísticos de gran tamaño (LLM) para razonar. Es un desafío utilizar agentes en entornos empresariales que proporcionan respuestas sin una explicación clara o que muestran un comportamiento incoherente.
Estos desafíos pueden abordarse utilizando IBM watsonx Orchestrate que proporciona una plataforma estructurada, que soporta autoalojamiento, razonamiento basado en herramientas, llamadas a API y control de nivel empresarial sin necesidad de código de orquestación personalizado.
Dynamiq construyó 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 coste 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 de herramienta. Gracias a la integración de IBM watsonx Orchestrate, Dynamiq garantizó que todas las decisiones fueran totalmente trazables, auditables y documentadas, lo que permitió reducir el tiempo de revisión de los contratos de 90 minutos a 45 sin comprometer el gobierno.
En este tutorial, aprenderá cómo crear un agente de IA en watsonx Orchestrate con el Agent Development Kit (ADK) de watsonx Orchestrate. En los sistemas de IA basados en LangChain o LangGraph, los desarrolladores suelen gestionar manualmente los intentos, 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 implementaciones de agentes coherentes y preparadas para la empresa.
Utilizará Python para crear la lógica de evaluación de riesgos, definir el comportamiento de los agentes e incorporar Langfuse para monitorizar y mejorar el comportamiento de los agentes con rastros de ejecución reales. También puede encontrar este tutorial en GitHub.
Langfuse es una plataforma de observabilidad LLM de código abierto construida sobre OpenTelemetry para monitorizar aplicaciones y agentes LLM. Utiliza telemetría (trazas, métricas y registros) para monitorizar las trazas de las ejecuciones de agentes, incluyendo llamadas a LLM, llamadas a herramientas, uso de tokens, metadatos y latencia a nivel de solicitud y por sesión.
Permite a los desarrolladores obtener perspectivas profundas sobre cómo los agentes se desempeñan en escenarios del mundo real, identificar las causas raíz de los outputs incorrectos y optimizar sistemáticamente el comportamiento de los agentes para una mayor fiabilidad y eficiencia.
El objetivo de este tutorial es crear un agente de IA para el gobierno empresarial que evalúe el riesgo de los proveedores mediante 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 justifica sus decisiones.
También soporta 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 proveedores completado integrado en este tutorial. Explore cómo el agente clasifica a los proveedores, responde a las preguntas y traza su razonamiento a través de Langfuse, para que tenga una visión clara de lo que está construyendo antes de empezar.
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 usar IBM Cloud para crear una prueba gratuita de 30 días cuando no tenga cuenta.
Una clave de API de watsonx Orchestrate de la interfaz de usuario (IU) de Orchestrate.
Un ADK de watsonx Orchestrate instalado en su sistema.
Inicia sesión en watsonx Orchestrate a través de IBM Cloud y abre la IU de watsonx Orchestrate. Vaya a los detalles de la API después de abrir Configuración en el menú de 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 local (Software Development Kit) para construir y probar la lógica de agentes.
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 Orchestrate (CLI) proporcionada por el ADK en Powershell. Empiece navegando hasta el directorio donde quieres construir su proyecto. A continuación, cree un nuevo entorno virtual de Python:
Se crea un entorno de 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.
A continuación, active el entorno virtual. Su sistema operativo determina qué comando de activación utilizar.
En Windows:
macOS y Linux:
Una vez activado, la instrucción de su terminal mostrará .venv al principio para mostrar que está trabajando en un entorno virtual.
Con el entorno virtual activo, instale el ADK de watsonx Orchestrate en su equipo local. Para utilizar el ADK, conéctelo a su entorno watsonx Orchestrate existente. Ejecute el siguiente comando en PowerShell:
Puede seguir los próximos pasos de la instalación de ADK siguiendo los pasos del documento oficial de instalación.
Nota: Este tutorial ejecuta el tiempo de ejecución de watsonx Orchestrate Developer Edition de forma local 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 añada los siguientes valores:
Este .env es necesario para ejecutar el servidor. En los próximos 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: El kit de desarrollo WatsonX Orchestrate ADK es compatible con varios tipos de entornos, incluidos IBM Cloud, AWS e implementaciones locales. En este tutorial, utilizamos el entorno local y nos autenticamos con una clave API a través de la CLI de ADK. El 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 añadir su entorno Watsonx Orchestrate:
En este caso, service-instance-url es la URL de su instancia de Watsonx Orchestrate. Puede encontrar esta información en la misma pestaña de detalles de la API, en la configuración de la IU de watsonx Orchestrate.
A continuación, active el entorno que añadió:
Ahora, cuando se le solicite, introduzca la clave de watsonx Orchestrate obtenida en el paso 1. Cuando se haya activado el entorno, cualquier comando posterior relacionado con el ADK, como la importación de agentes, herramientas o la ejecución del servidor, se ejecutará en el entorno de watsonx Orchestrate.
Nota: Si quiere ejecutar todo localmente con la 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 pruebas locales.
En este paso, creará la plantilla marco del agente que contiene la definición, las herramientas y el código fuente de su agente de inteligencia de riesgos de proveedores. A continuación, cree la estructura de carpetas necesaria para el desarrollo local basado en ADK:
Puede añadir el comando que se indica 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, las reglas de razonamiento y la configuración del modelo del agente. Determina cómo responde el sistema 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 las herramientas personalizadas y la lógica empresarial.
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:
Los próximos pasos a seguir son la observabilidad del agente, donde se analiza el comportamiento del agente en tiempo de ejecución, por ejemplo, las herramientas a las que se llama, la latencia y dónde se producen los errores. Para ello, active la observabilidad de Langfuse en el entorno de watsonx Orchestrate ADK.
En este tutorial, se utiliza la versión SaaS de Langfuse, que le permite capturar rastros sin ejecutar Langfuse localmente.
Asegúrese de que el servidor Watsonx Orchestrate esté funcionando (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. En la configuración del proyecto, copie el identificador del proyecto, la clave pública, la clave secreta y la URL del anfitrión.
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 está en funcionamiento, puede probar el agente.
El próximo paso es definir el agente de inteligencia de riesgos de proveedores. Los agentes de 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.
En el directorio de agentes, cree un archivo llamado vendor-risk-agent.yaml. Este archivo constituye la capa de gestión de instrucciones del agente, que garantiza que todas las respuestas se basen en un razonamiento determinista, en lugar de en una inferencia 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 agent/vendor-risk-agent.yaml. Guarde el archivo después.
Esta configuración garantiza que el agente se comporte de forma predecible en las preguntas de qué, por qué, cómo y de comparación. El sistema evita las alucinaciones al prohibir las suposiciones sobre calificaciones financieras o significados de riesgo a menos que el resultado de la herramienta los defina 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 de afinar un modelo para un comportamiento específico de un dominio, este tutorial demuestra cómo el razonamiento determinista basado en reglas puede implementarse mediante herramientas Python que aseguran resultados consistentes.
Dentro de la carpeta src, cree un archivo llamado main.py. Este archivo contiene el conjunto de datos de proveedores que hemos creado, las reglas de evaluación de riesgos y una herramienta de Python llamada evaluate_all_vendor_risks que proporciona la lógica al agente.
La lógica del riesgo se basa en reglas. En cuanto a señales de alto riesgo, una empresa puede recibir una puntuación de riesgo debido a su rendimiento financiero, incidentes de seguridad en el pasado o investigaciones 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 crea como una herramienta de watsonx Orchestrate, por lo que el agente puede llamarla durante la ejecución. La herramienta devuelve un output estructurado que incluye el nivel de riesgo final y las razones exactas que causaron la clasificación.
Nota: El archivo main.py incluido en este tutorial es la última versión actualizada de la lógica de evaluación de riesgos de los proveedores. Los primeros conjuntos de código provocaban comportamientos erróneos de los agentes, que se analizaban mediante rastreos de Langfuse. Puede encontrar los rastros de Langfuse en las capturas de pantalla que aparecen en los últimos pasos de este tutorial.
A continuación se muestra el código completo del archivo main.py utilizado en este tutorial. 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 agentes, src y herramientas).
Primero, importe la herramienta Python para que watsonx Orchestrate pueda registrarla como una 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.
A continuación, el agente de inteligencia de riesgos de proveedores 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 de chat de watsonx Orchestrate en su navegador. Desde el selector de agentes, seleccione Vendor_Risk_Intelligence_Agent y comience a hacer preguntas relacionadas con el riesgo del proveedor.
Para comprobar que el agente responde correctamente (y que invoca la herramienta de Python de forma determinista), a continuación se incluyen algunas preguntas de ejemplo que puede utilizar para realizar pruebas:
Mientras interactúa con el agente, abra el panel de control de Langfuse en su navegador. Cada consulta de usuario crea un nuevo seguimiento e incluye un session_id y un ID de usuario. Estos registros documentan la ruta de ejecución completa del agente. Al seleccionar un rastro, puede analizar:
La entrada y output completos del agente
La invocación de la herramienta Python
Los datos estructurados que devuelve la herramienta
El proceso de razonamiento seguido para llegar a la respuesta final
Latencia para cada paso del proceso
Flujo de conversación por sesiones para varias preguntas
Esta observabilidad le 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 la invocación, el paso de razonamiento y la latencia de respuesta de cada herramienta, lo que facilita entender por qué se ha producido 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 correcciones 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 el output estructurado 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 a un desarrollo seguro y sólido de agentes basándose en el feedback de los usuarios.
Explore la demostración interactiva a continuación para explorar el agente de riesgo del proveedor y el rastreo de Langfuse en acción.
Este tutorial le ha guiado en la creación de un agente de IA estructurado y fiable con watsonx Orchestrate, desarrollado para la creación de agentes de nivel empresarial. Con la integración de lógica Python basada en reglas sencilla, instrucciones claras de agente y herramientas reutilizables, ha implementado 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 ha hecho que sea fácil detectar el comportamiento de los agentes e identificar los problemas de razonamiento para mejorar continuamente la precisión sin conjeturas. Este enfoque ayuda a las empresas a optimizar los sistemas de agentes de extremo a extremo, automatizar flujos de trabajo complejos e implementar 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 agénticos complejos y aplicaciones de IA más rápido, con un gobierno más sólido y un razonamiento más claro y un tiempo de desarrollo reducido.
Cree, implemente y gestione potentes 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 puede confiar.
Los servicios de IA de IBM Consulting ayudan a reinventar la forma de trabajar de las empresas usando IA para la transformación.