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 infraestructuras/marcos comunicarse y coordinarse sin una lógica de integración personalizada.

ACP es especialmente valioso para entornos de IA empresarial, 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 empresarial modernos.

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

La mayoría de las infraestructuras de IA agéntica manejan la comunicación mediante el uso de 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 de la infraestructura para la forma en que 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 desacoplar la comunicación de la lógica interna de un agente, ACP permite a los equipos mezclar y combinar agentes creados con diferentes infraestructuras/marcos de agente 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 admite el diseño de sistemas modulares y transparentes que se alinean con los estándares modernos de la industria.

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 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 retroalimentación estructurada.
• crewAI: una infraestructura de código abierto para Orchestrate® 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: BeeAI desarrolló el ACP-SDK para promover la interoperabilidad independiente de la infraestructura en sistemas multiagente. Las referencias y las implementaciones se mantienen en el repositorio de ACP GitHub.
• Agent-Ops (opcional): una plataforma de monitoreo y observabilidad para agentes de IA. En este proyecto, se puede utilizar para rastrear el comportamiento de los agentes y visualizar flujos de trabajo de múltiples agentes.

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

El flujo de trabajo comienza cuando el usuario proporciona una URL. A partir de ahí, un sistema modular e independiente de infraestructura de agentes especializados transforma el contenido de la página web en un artefacto creativo, una canción original, acompañado de críticas de estilo profesional. Todos los componentes funcionan en conjunto para combinar estos resultados 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 insights analíticos.

Este flujo de trabajo ilustra cómo ACP permite que un sistema de IA agéntica multiagente coordine la colaboración entre agentes desarrollados con dos infraestructuras distintas: 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, capaz de Orquestate agentes a través de infraestructura mientras produce resultados cohesivos de extremo a extremo 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, las fortalezas, las preocupaciones y las recomendaciones.
• Agente de informes de Markdown (crewAI): combina los datos de salida 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. Luego, ACP envía la canción generada al agente de A&R para su crítica.
3. El agente de A&R evalúa la canción y proporciona retroalimentación detallada sobre su potencial, fortalezas y áreas de mejora. También puede identificar audiencias 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. Finalmente, 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 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 de múltiples agentes.

ACP proporciona un sistema de mensajería común que permite a los agentes creados con diferentes infraestructuras intercambiar información de manera 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 le pide al usuario que ingrese 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 devuelve feedback, también a través de eventos transmitidos.
4. Enviar al agente de informes de Markdown (servidor de CrewAI, puerto 8000):
   • El cliente empaqueta la canción y la crítica en un solo mensaje y lo envía de vuelta al servidor de crewAI, donde el agente de informes de Markdown formatea todo en un informe.
5. Guarde la salida:
   • El cliente escribe el informe final de Markdown en un archivo: a&r_feedback.md .

El acp-sdk  es la biblioteca central que permite la comunicación estandarizada de agentes en este proyecto.

Funciones clave de acp-sdk :

• Estructura del mensaje:
  • Garantiza que toda la comunicación sea estructurada y coherente (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 comenzar, aquí hay una descripción general rápida de las herramientas y los servicios de proveedores que necesitará.

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

En las secciones siguientes, encontrará instrucciones paso a paso para instalar, configurar y usar 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 Orchestrate tareas
• Ollama: para ejecutar LLM locales (si Ollama es su proveedor seleccionado)
• OpenRouter: se requiere clave API para usar 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 monitoreo de agentes.
• Terminal o IDE: un emulador de terminal o entorno de desarrollo integrado (IDE) como código VS (recomendado para gestionar múltiples terminales y ver la salida 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 localmente.

Ambas infraestructuras son independientes del proveedor, por lo que puede cambiar a otros servicios LLM actualizando los ajustes de configuración. Su configuración puede variar según el proveedor de LLM que elija. Además, este tutorial incluye una configuración preconfigurada opcional para usar 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 usar el servidor de agentes BeeAI preconfigurado con modelos de lenguaje basados en la nube.

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

1. Regístrese en OpenRouter
   • Vaya a OpenRouter y cree una cuenta gratuita.
2. Generar una clave de API
   • En su panel 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 planea utilizar Ollama como su proveedor de LLM para el agente de crewAI, siga estos pasos:

1.  Descargue e instale Olama
   • Visite Ollama e instale la aplicación para su sistema operativo.
2.  Inicie el servidor Olama
   • 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 su proveedor de LLM para el servidor de crewAI, siga estos pasos:

1.  Iniciar sesión en watsonx.ai
   • Utilice su cuenta de IBM Cloud para iniciar sesión en IBM Cloud.
2. Cree un proyecto watsonx.ai.
   • En el panel de watsonx.ai, cree un nuevo proyecto y guarde su ID de proyecto.
3.  Crear 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® tiempo de ejecución a su proyecto
   • En el panel de watsonx.ai, vincule la instancia del servicio de tiempo de ejecución al proyecto que creó.

IBM watsonx.ai se utiliza como proveedor opcional de nube de IA para agentes de crewAI en este tutorial.

AgentOps es un servicio opcional para rastrear, monitorear y visualizar sus flujos de trabajo de múltiples agentes.
Si desea utilizar AgentOps en este proyecto, siga estos pasos:

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

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

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

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

Dentro de una 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 por mantener abierta su terminal actual, luego abra dos terminales más y asegúrese de que los tres se dirijan a los directorios correctos (como se muestra en el siguiente paso).

¿Usa un IDE?

Si está utilizando un IDE como Visual Studio Code*, puede usar la característica Split Terminal para administrar múltiples terminales lado a lado.

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

Navegación de terminales

Cada terminal es responsable de uno de los siguientes componentes:

1. Terminal de cliente ACP.
   Directorio: acp_tutorial
   
   cd acp_tutorial
   
   
2. BeeAI agent server terminal
   Directorio: beeai_agent_server
   
   cd beeai_agent_server
   
   
3. Directorio del terminal del sistema del
   agente de crewAI: 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 administrador de paquetes de Python basado en Rust para administrar 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 mediante 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

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

Ahora instale dependencias en cada terminal usando:

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

Con BeeAI instalado, use 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 ingrese su clave API y los detalles del modelo.

Para confirmar su configuración, use:

Este paso debe generar sus resultados LLM_API_BASE , LLM_API_KEY, YLLM_MODEL .

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

Ejemplo .env para OpenRouter

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

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

Solución de problemas

Si es necesario, puede actualizar o reiniciar la plataforma:

En el crewai_agent_server  directorio, cree un .env  copiando 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 los documentos de configuración de LLM de crewAI.

Actualizar el código del agente de crewAI

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

Asegúrese de que los nombres de las variables de entorno en su .env  coincida 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 la terminal beeai_agent_server:

Debería ver un resultado que confirme que el servidor se inició el http://127.0.0.1:9000 , junto con controles de estado periódicos:

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

Inicie el servidor del agente de crewAI

En la terminal crewai_agent_server:

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

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 gratuita):

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 en la lista y son accesibles, podemos confirmar que estos agentes interoperan correctamente.

En la terminal dedicada al servidor acp-client (dentro acp_tutorial  directorio):

Dentro de la terminal, se le dará una instrucción para ingresar una URL. Esta entrada activa el flujo de trabajo multiagente.

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

1. Ingrese cualquier URL que desee que procesen los agentes. Por ejemplo:
   
   URL: https://www.ibm.com/mx-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 resultados 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 infraestructuras diferentes de multiagente 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 lógica de integración personalizada. Este enfoque mejora la modularidad, el escalamiento 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, generalmente en formatos como JSON, y enriquecidos con metadatos para garantizar la coherencia y la claridad en las interacciones con los agentes. Ya sea que esté utilizando agentes impulsados por OpenAI, Anthropic u otros modelos de IA, ACP proporciona una capa de mensajería compartida que admite la interoperabilidad independiente de la infraestructura.

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 Power®  de ACP para permitir sistemas de IA multiagente sin problemas, 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, presione Crtl + C  para detener el servidor. Este paso intenta un apagado correcto.

Debería ver resultados como:

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 el ID de proceso (PID)

Ejecute el siguiente comando para localizar el proceso del servidor:

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

Matar el proceso. Utilice el PID para detenerlo a la fuerza:

Repita este proceso para cada servidor si es necesario.

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