Uso de ACP para la interoperabilidad de agentes de IA: creación de flujos de trabajo multiagente

En este tutorial, utilizará los protocolos de comunicación de agentes (ACP) para explorar un flujo de trabajo de IA multiagente y multiplataforma que demuestra la colaboración de agentes en tiempo real con BeeAI y crewAI. ACP funciona como una capa de mensajería compartida y de estándar abierto que permite a los agentes de diferentes marcos comunicarse y coordinarse sin necesidad de una lógica de integración personalizada.

ACP es especialmente valioso para entornos empresariales de IA, donde los equipos a menudo necesitan crear agentes y flujos de trabajo en diversas plataformas, herramientas e infraestructuras. Al proporcionar una capa de mensajería estandarizada, ACP permite una colaboración de agentes escalable, segura y modular que satisface las demandas de los sistemas de IA empresariales modernos.

Este proyecto demuestra la interoperabilidad de los agentes al permitir que los agentes impulsados por IA colaboren a través de silos de marco, combinando capacidades de agentes como investigación, generación de contenido y comentarios en un flujo de trabajo unificado.

La mayoría de los marcos de IA agéntica gestionan la comunicación mediante sistemas personalizados o cerrados. Esta arquitectura dificulta la conexión de agentes entre cadenas de herramientas, equipos o infraestructuras, especialmente cuando se combinan componentes de diferentes sistemas de IA.

ACP introduce un formato de mensajería estandarizado e independiente del marco sobre cómo los agentes autónomos envían, reciben e interpretan mensajes. Los mensajes están estructurados, normalmente en JSON, y contienen metadatos para enriquecer las interacciones de los agentes con claridad y coherencia.

Al desvincular la comunicación de la lógica interna de un agente, ACP permite a los equipos mezclar y combinar agentes creados con diferentes marcos de agentes de IA, como BeeAI, CrewAI, LangChain o LangGraph, sin necesidad de código de integración personalizado. Este enfoque aumenta la escalabilidad, simplifica la automatización y respalda el diseño de sistemas modulares y transparentes que se alinean con los estándares modernos de los sectores.

Al final de este tutorial, habrá visto un ejemplo práctico de ACP y tendrá experiencia práctica en el uso de las siguientes tecnologías:

• BeeAI: un marco de agentes flexible para crear y gestionar agentes de IA. En este proyecto, se utiliza para ejecutar el agente A&R (Artista y Repertorio) que critica la canción generada y proporciona comentarios estructurados.
• crewAI: un marco de código abierto para orquestar flujos de trabajo de múltiples agentes. Aquí, se utiliza para coordinar la investigación, la composición de canciones y los agentes de informes de Markdown.
• acp-sdk: el ACP-SDK fue desarrollado por BeeAI para promover la interoperabilidad independiente del marco en sistemas multiagente. Las referencias y las implementaciones se mantienen en el repositorio ACP GitHub.
• Agent-Ops (opcional): una plataforma de monitorización y observabilidad para agentes de IA. En este proyecto, se puede utilizar para rastrear el comportamiento de los agentes y visualizar flujos de trabajo multiagente.

Este proyecto demuestra un flujo de trabajo multiagente que muestra cómo ACP (a través de acp-sdk) puede optimizar la colaboración coherente y observable en todos los ecosistemas.

El flujo de trabajo comienza cuando el usuario proporciona una URL. A partir de ahí, un sistema modular e independiente del marco de trabajo, compuesto por agentes especializados, transforma el contenido de la página web en una canción original acompañada de una crítica de estilo profesional. Todos los componentes trabajan en conjunto para combinar estos outputs en un único informe Markdown unificado y legible por humanos. Este resultado final representa una transformación completa de los datos originales, combinando la generación creativa con el conocimiento analítico.

Este flujo de trabajo ilustra cómo ACP permite un sistema de IA agéntica multiagente, para coordinar la colaboración entre agentes desarrollados con dos marcos: BeeAI y crewAI, al servir como una capa de comunicación compartida en todo el sistema.

Al separar la comunicación de la implementación, el sistema sigue siendo modular y extensible, y es capaz de orquestar agentes en distintos marcos y de producir outputs coherentes y completos a partir de contenido web no estructurado.

Agentes ACP

Este proyecto utiliza cuatro agentes de IA especializados:

• Agente de investigación (crewAI): extrae temas e información clave de la URL proporcionada.
• Agente SongWriter (crewAI): genera una canción original basada en la investigación.
• Agente de A&R (BeeAI): proporciona una crítica de estilo profesional de la canción, incluido el potencial de éxito, los puntos fuertes, las preocupaciones y las recomendaciones.
• Agente de informes de Markdown (crewAI): combina el output del equipo de redacción de canciones y los agentes de A&R y los formatea en un informe de Markdown limpio y legible.

Flujo de trabajo de proyectos de composición y crítica

1. El flujo de trabajo comienza cuando el usuario envía una URL a través de la aplicación cliente. El cliente envía esta URL al agente de investigación mediante mensajes ACP, que luego lee y analiza el contenido de la página web para extraer temas relevantes.
2. A continuación, el agente SongWriter recibe los datos de la investigación y compone una canción original inspirada en los temas identificados en el material de origen durante el análisis. La ACP envía la canción generada al agente de A&R para su revisión.
3. El agente de A&R evalúa la canción y proporciona comentarios detallados sobre su potencial, fortalezas y áreas de mejora. También puede identificar públicos objetivo, sugerir influencias estilísticas y ofrecer comparaciones con artistas o géneros similares. Esta crítica, junto con la canción, se reenvía al agente de informes de Markdown.
4. Por último, el agente de informes de Markdown formatea la canción y la crítica en un informe de Markdown limpio y legible, que se guarda y se presenta al usuario.

A lo largo del flujo de trabajo, los mensajes intercambiados entre agentes se estructuran como objetos JSON enriquecidos con metadatos. Estos metadatos guían la comprensión de cada agente del contenido del mensaje, el contexto y las respuestas esperadas.

Este flujo de trabajo demuestra un patrón reutilizable aplicable a cualquier caso de uso que requiera orquestar pipelines de transformación de datos y análisis multiagente.

ACP proporciona un sistema de mensajería común que permite a los agentes creados con diferentes marcos intercambiar información de forma estandarizada. Este protocolo abierto permite a los agentes interoperar sin necesidad de integraciones personalizadas o lógica interna compartida.

El cliente ACP (acp-client.py ) es el orquestador del flujo de trabajo multiagente. Coordina la comunicación entre el usuario y los agentes (crewAI y BeeAI) mediante ACP.

Descripción general del flujo de trabajo del cliente ACP

1. Instrucción para entrada:
   • El cliente pide al usuario que introduzca una URL.
2. Enviar al servidor de crewAI (puerto 8000):
   • El cliente construye un mensaje ACP que contiene la URL y lo envía al servidor de crewAI que se ejecuta en el puerto 8000.
   • El servidor realiza tanto la investigación como la composición de canciones, y envía las letras generadas al cliente como eventos ACP transmitidos.
3. Enviar al servidor BeeAI (Puerto 9000):
   • La canción se envía como un mensaje ACP al servidor BeeAI en el puerto 9000.
   • El agente de A&R critica la canción y envía sus comentarios, también a través de eventos transmitidos en directo.
4. Enviar al agente de informes Markdown (servidor CrewAI, puerto 8000):
   • El cliente empaqueta la canción y la crítica en un único mensaje y lo envía de vuelta al servidor crewAI, donde el agente de informes Markdown lo formatea todo en un informe.
5. Guardar el output:
   • El cliente escribe el informe final de Markdown en un archivo: a&r_feedback.md .

La función acp-sdk  es la biblioteca principal que permite la comunicación estandarizada de agentes en este proyecto.

Funciones clave de acp-sdk :

• Estructura del mensaje:
  • Garantiza que todas las comunicaciones estén estructuradas y sean coherentes (normalmente, JSON con metadatos).
  • La biblioteca implementa clases (Message, MessagePart) y tipos de eventos (MessagePartEvent, GenericEvent, MessageCompletedEvent)
• Comunicación con el cliente:
  • La clase Client se utiliza para conectarse a servidores de agentes y enviar o recibir
    mensajes ACP,
  • Admite respuestas de transmisión para que los agentes puedan enviar resultados parciales o actualizaciones.
• Integración del servidor del agente:
  • Los agentes (en crewAI y BeeAI) se implementan como servidores compatibles con ACP.
  • Exponen endpoints que aceptan mensajes ACP y devuelven eventos ACP.

Ejemplo de uso del cliente:

Estos son los requisitos del sistema para ejecutar este proyecto:

• Sistema operativo: macOS, Linux o Windows
• Memoria (RAM): >= 8 GB (Recomendado: 16 GB o más, especialmente si se ejecutan LLM locales con Ollama)
• Espacio en disco: >= 5 GB de espacio libre (recomendado:10 GB o más para ejecutar el entorno Python, cualquier modelo local y archivos generados)
  • Nota: Si utiliza Ollama para LLM locales, cada modelo puede requerir de 4 a 8 GB o más.
• Python: >= 3,11

Antes de empezar, he aquí una breve descripción general de las herramientas y los servicios de proveedores que necesitará.

La siguiente lista cubre los principales marcos, plataformas y API necesarios para el flujo de trabajo multiagente.

En las secciones siguientes, encontrará instrucciones paso a paso para instalar, configurar y utilizar cada herramienta y proveedor para que pueda configurar su entorno.

• Gestor de paquetes UV: (gestor de paquetes Python basado en Rust para la gestión de dependencias)
• BeeAI Platform y CLI: necesarios para ejecutar el servidor de agentes BeeAI
• crewAI: necesario para ejecutar el servidor de crewAI y orquestar tareas
• Ollama: para ejecutar LLM locales (si Ollama es su proveedor seleccionado)
• OpenRouter: clave de API necesaria para utilizar el servidor de agentes BeeAI preconfigurado
  • Nota: puede cambiar a otros proveedores editando el archivo .env y actualizando el código del agente si es necesario, o a través de la CLI de BeeAI.
• IBM® watsonx.ai: Clave API (otro proveedor opcional)
• Clave de API de AgentOps: opcional para el seguimiento y la monitorización de agentes.
• Terminal o IDE: un emulador de terminal o un entorno de desarrollo integrado (IDE) como el código VS (recomendado para gestionar varios terminales y ver el output de Markdown)

BeeAI y crewAI están diseñados para trabajar con una variedad de proveedores de modelos de lenguaje, lo que los hace flexibles para diferentes entornos y casos de uso. En este tutorial, OpenRouter es el proveedor de LLM para el agente BeeAI, mientras que Ollama se utiliza para los agentes de crewAI de forma local.

Ambos marcos son independientes del proveedor, por lo que puede cambiar a otros servicios LLM al actualizar los ajustes de configuración. Su configuración puede variar en función del proveedor de LLM que elija. Además, este tutorial incluye una configuración preconfigurada opcional para utilizar IBM watsonx.ai como proveedor alternativo basado en la nube.

También puede utilizar su proveedor y modelo de LLM preferido; sin embargo, tenga en cuenta que solo se han probado las configuraciones que se muestran en este tutorial. Otros proveedores y modelos pueden requerir configuraciones o ajustes adicionales.

Los siguientes requisitos son para los tres proveedores admitidos en este proyecto:

Necesitará una clave de API de OpenRouter para utilizar el servidor de agentes BeeAI preconfigurado con modelos de lenguaje basados en la nube.

Para utilizar OpenRouter como proveedor de LLM para el agente BeeAI, siga estos pasos:

1. Regístrese en OpenRouter
   • Vaya a OpenRouter y cree una cuenta gratuita.
2. Genere una clave API
   • En su panel de control de OpenRouter, genere una nueva clave API
3. Elija un modelo
   • Examine la lista de modelos de OpenRouter y seleccione el modelo que desee utilizar (por ejemplo,deepseek/deepseek-r1-distill-llama-70b:free ).

Nota: El modelo gratuito puede ser diferente dependiendo de cuándo se ejecute este tutorial. Para ver los modelos gratuitos, consulte la lista de modelos de niveles gratuitos de OpenRouter.

Si tiene previsto utilizar Ollama como proveedor de LLM para el agente de crewAI, siga estos pasos:

1.  Descargue e instale Ollama
   • Visite Ollama e instale la aplicación para su sistema operativo.
2.  Inicie el servidor Ollama
   • En su terminal, ejecute:
     ollama serve
3. Extraer un modelo
   • Descargue su modelo específico (por ejemplo, llama3):
     ollama pull llama3

Para utilizar IBM® watsonx.ai como proveedor de LLM para el servidor de crewAI, siga estos pasos:

1.  Inicie sesión en watsonx.ai
   • Utilice su cuenta de IBM® Cloud para iniciar sesión en IBM Cloud.
2. Cree un proyecto en watsonx.ai
   • En el panel de control de watsonx.ai, cree un nuevo proyecto y guarde su ID.
3.  Cree una instancia de servicio de watsonx.ai tiempo de ejecución
   • Elija el plan Lite (instancia gratuita).
4.  Genere una clave de API de watsonx
   • En IBM Cloud, vaya a la configuración de su cuenta y genere una nueva clave de API.
5.  Asocie el servicio watsonx.ai de tiempo de ejecución a su proyecto
   • En el panel de control de watsonx.ai, vincule la instancia del servicio de tiempo de ejecución al proyecto que ha creado.

En este tutorial, IBM watsonx.ai se utiliza como proveedor opcional de LLM en la nube para los agentes de crewAI.

AgentOps es un servicio opcional para rastrear, monitorizar y visualizar sus flujos de trabajo multiagente.
Si desea utilizar AgentOps en este proyecto, siga estos pasos:

1.  Regístrese en AgentOps
   • Vaya a AgentOps y cree una cuenta gratuita.
2.  Genere una clave de API
   • En su panel de control de AgentOps, genere una nueva clave de API.
3.  Agregue su clave API a su archivo .env
   •  Ejemplo de configuración:
     AGENTOPS_API_KEY=your_agentops_api_key
4.  Verifique la Integración
   • Cuando ejecuta sus agentes, los rastreos y registros deben aparecer en su panel de control de AgentOps si la clave API está configurada correctamente.

AgentOps no es necesario para ejecutar el flujo de trabajo, pero puede ayudarle a monitorizar la actividad de los agentes y depurar las interacciones entre varios agentes.

Para ejecutar este proyecto, clone el repositorio de GitHub utilizando https://github.com/IBM/ibmdotcom-tutorials.git como URL HTTPS. Para conocer con detalle los pasos para clonar un repositorio, consulte la documentación de GitHub.

Este tutorial se puede encontrar dentro del directorio de proyectos del repositorio.

Dentro de un terminal, navegue hasta el directorio de este tutorial:

Este proyecto requiere tres scripts de Python separados para ejecutarse simultáneamente para cada componente del sistema multiagente. Como resultado, deberá abrir tres ventanas o pestañas de terminal.

Comience manteniendo abierto su terminal actual, luego abra dos terminales más y asegúrese de que los tres se desplazan a los directorios correctos (como se muestra en el siguiente paso).

¿Utiliza un IDE?

Si utiliza un IDE como Visual Studio Code*, puede utilizar la característica Split Terminal para gestionar varios terminales lado a lado.

De lo contrario, abra tres ventanas de terminal independientes y navegue cada una hasta el subdirectorio adecuado.

Navegación por terminales

Cada terminal es responsable de uno de los siguientes componentes:

1. Terminal de cliente ACP.
   Directorio: acp_tutorial
   
   cd acp_tutorial
   
   
2. Terminal del servidor del agente BeeAI
   Directorio: beeai_agent_server
   
   cd beeai_agent_server
   
   
3. Terminal del sistema agente crewAI
   Directorio: crewai_agent_server
   
   cd crewai_agent_server
   
   

Cada componente se ejecuta en su propio entorno virtual para garantizar una gestión limpia de las dependencias. Este tutorial utiliza UV, un gestor de paquetes de Python basado en Rust para gestionar y sincronizar entornos.

Nota: Asegúrese de que Python 3.11 o posterior esté instalado antes de continuar.

Instalar UV

Si aún no lo ha hecho, instale UV utilizando Homebrew (recomendado para macOS y Linux):

Nota para usuarios de Windows: instale WSL (Windows Subsystems for Linux) y siga las instrucciones de Linux dentro de su terminal WSL.

Crear y activar un entorno virtual (en cada terminal)

En cada terminal (BeeAI, crewAI y cliente ACP), ejecute el siguiente código:

Este paso creará y activará un .venv  en el directorio actual

Ejecutar uv venv  dentro de cada directorio de proyecto ayuda a aislar entornos por componente.

Ahora instale las dependencias en cada terminal utilizando:

Este paso instala las dependencias enumeradas en el pyproject.toml  para cada componente.

Con BeeAI instalado, utilice la CLI para iniciar la plataforma BeeAI en el beeai_agent_server :

Nota: En la primera ejecución, este paso puede tardar varios minutos.

Configure su proveedor de LLM (OpenRouter)

Ejecute el siguiente comando para configurar el proveedor y el modelo LLM a través de la CLI interactiva:

Siga las instrucciones para seleccionar OpenRouter e introduzca su clave de API y los detalles del modelo.

Para confirmar su configuración, utilice:

Este paso debería generar su configuración LLM_API_BASE , LLM_API_KEY, yLLM_MODEL .

Como alternativa, los usuarios avanzados pueden editar manualmente un .env  con los valores adecuados.

Ejemplo .env para OpenRouter

Para verificar que BeeAI funciona, envíe una instrucción de prueba:

Una respuesta válida confirma que la plataforma está activa.

Resolución de problemas

Si es necesario, puede actualizar o reiniciar la plataforma:

En el crewai_agent_server  directorio, cree un .env  al copiar la plantilla:

Abrir .env  y descomente la configuración de su proveedor de modelos preferido. Este proyecto admite:

• Ollama (inferencia local), o
• IBM watsonx.ai (inferencia en la nube)

También puede personalizar su propio proveedor utilizando la documentación de configuración de LLM de crewAI.

Actualice el código del agente de crewAI

En acp_crew.py , localice el llm = LLM (...)  bloquee y descomente la sección correspondiente para que coincida con su .env  configuración.

Asegúrese de que los nombres de las variables de entorno en su .env  coinciden con lo esperado en el código.

Una vez configurados tanto BeeAI como crewAI, inicie los servidores de agentes en sus respectivos terminales.

Inicie el servidor del agente BeeAI

En el terminal beeai_agent_server:

Debería ver un output que confirma que el servidor se ha iniciado en http://127.0.0.1:9000 , junto con controles de estado periódicos:

El terminal debe registrar pings de comprobación del estado cada dos segundos. A 200 OK  estado significa que el servidor está en buen estado.

Inicie el servidor del agente de crewAI

En el terminal crewai_agent_server:

Debería ver el servidor ejecutándose en http://127.0.0.1:8000 , junto con 200 OK  registros.

Confirme que todos los agentes se están ejecutando

BeeAI reconoce automáticamente los agentes compatibles con ACP creados localmente. Utilice la CLI de BeeAI para confirmar que todos los agentes locales están registrados y en buen estado (este paso puede ejecutarse en cualquier terminal libre):

Debería ver entradas para:

• artist-repertoire-agent (BeeAI, puerto 9000)
• markdown_report_agent  (Puerto 8000 de CrewAI)
• song_writer_agent  (Puerto 8000 de CrewAI)

Si todos están enumerados y son accesibles, podemos confirmar que estos agentes interoperan correctamente.

En el terminal dedicado al servidor acp-client (dentro acp_tutorial  directorio):

Dentro del terminal, se le pedirá que introduzca una URL. Esta entrada desencadena el flujo de trabajo multiagente.

Con todos los agentes y el cliente/servidor en funcionamiento, ¡ya está listo para iniciar el proyecto ACP!

1. Introduzca cualquier URL que desee que procesen los agentes. Por ejemplo:
   
   URL: https://www.ibm.com/es-es/think/topics/agent-communication-protocol
   
   
2. Verá registros de estado como:

1. El cliente envía la URL al agente de crewAI que investiga la página y genera material de composición.
2. El agente de crewAI escribe una canción basada en la investigación.
3. La canción se envía al agente de BeeAI para la crítica de A&R (artista y repertorio).
4. El agente BeeAI devuelve feedback y sugerencias estructurados.
5. El cliente muestra la canción generada, la crítica y guarda el feedback en a&r_feedback.md .

Nota: los outputs de los modelos de lenguaje de gran tamaño (LLM) son probabilísticos y pueden variar cada vez que ejecuta el flujo de trabajo, incluso con la misma entrada.

En este tutorial, conectó dos marcos diferentes a través de un cliente/servidor ACP que expuso endpoints para que los agentes de IA colaboraran para generar y transformar datos. Al separar la comunicación del comportamiento de los agentes, ACP hace posible que los agentes creados con BeeAI, crewAI, LangChain y otros marcos de agentes trabajen juntos sin una lógica de integración personalizada. Este enfoque mejora la modularidad, el escalado y la interoperabilidad.

ACP es una iniciativa abierta impulsada por la necesidad de que los agentes envíen, reciban e interpreten mensajes. Los mensajes en ACP están estructurados (normalmente en formatos como JSON) y enriquecidos con metadatos para garantizar la coherencia y la claridad en las interacciones de los agentes. Tanto si utiliza agentes con tecnología OpenAI, Anthropic u otros modelos de IA, ACP proporciona una capa de mensajería compartida que admite la interoperabilidad independiente del marco.

Al seguir este flujo de trabajo, ha visto cómo los agentes creativos y analíticos pueden trabajar en armonía, transformando el contenido web no estructurado en una canción, una crítica profesional y un informe Markdown unificado. Este enfoque demuestra el potencial de ACP para habilitar sistemas de IA multiagente sin fisuras, escalables y flexibles.

Cuando haya terminado de experimentar con el sistema, siga estos pasos para apagar limpiamente todos los componentes en ejecución:

1. Detenga cada servidor en ejecución

En cada ventana de terminal, pulse Crtl + C  para detener el servidor. Este paso intenta realizar un apagado correcto.

Debería ver un output similar al siguiente:

2. Si el servidor se cuelga durante el apagado

Si un servidor deja de responder o se bloquea al apagarse (por ejemplo, se atasca en Waiting for application shutdown. ), puede finalizar manualmente el proceso:

Encuentre la ID del proceso (PID)

Ejecute el siguiente comando para localizar el proceso del servidor:

Identifique el PID del proceso que está intentando detener. Por ejemplo:

Elimine el proceso. Utilice el PID para detenerlo de manera forzada:

Repita este proceso para cada servidor si es necesario.

¡Eso es todo! Ha ejecutado correctamente un completo sistema multiagente multiplataforma utilizando ACP.