Uso do ACP para interoperabilidade de agentes de IA: criação de fluxos de trabalho multiagentes

Neste tutorial, você usará os Agent Communication Protocols (ACP) para explorar um fluxo de trabalho de IA multiagentes e multiplataformas, que demonstra a colaboração dos agentes em tempo real com o BeeAI e o crewAI. O ACP funciona como uma camada de mensagens compartilhada e de padrão aberto que permite que agentes de diferentes frameworks se comuniquem e coordenem sem lógica de integração personalizada.

O ACP é especialmente valioso para ambientes de IA corporativos, onde as equipes muitas vezes precisam criar agentes e fluxos de trabalho em diversas plataformas, ferramentas e infraestruturas. Ao oferecer uma camada de mensagens padronizada, o ACP possibilita a colaboração escalável, segura e modular de agentes, atendendo às demandas dos sistemas de IA corporativos modernos.

Este projeto demonstra a interoperabilidade de agentes, permitindo que agentes orientados por IA colaborem em silos de frameworks, combinando recursos de agentes como pesquisa, geração de conteúdo e feedback em um fluxo de trabalho unificado.

A maioria dos frameworks de IA agêntica lida com a comunicação usando sistemas personalizados ou fechados. Essa arquitetura dificulta a conexão de agentes em cadeias de ferramentas, equipes ou infraestruturas, especialmente quando se combinam componentes de diferentes sistemas de IA.

O ACP introduz um formato de mensagens padronizado e independente de framework sobre como os agentes autônomos enviam, recebem e interpretam mensagens. As mensagens são estruturadas, geralmente em JSON, e contêm metadados para enriquecer as interações dos agentes com clareza e consistência.

Ao desacoplar a comunicação da lógica interna de um agente, o ACP permite que as equipes combinem agentes criados com diferentes frameworks de agentes de IA, como o BeeAI, crewAI, CrewAI, LangChain ou LangGraph, sem a necessidade de um código de integração personalizado. Essa abordagem aumenta a escalabilidade, simplifica a automação e proporciona compatibilidade com o projeto de sistemas modulares transparentes que se alinham aos padrões modernos do setor.

Até o final deste tutorial, você terá visto um exemplo prático do ACP e terá experiência prática no uso das seguintes tecnologias:

• BeeAI: um framework de agentes flexível para criar e gerenciar agentes de IA. Nesse projeto, é usado o agente A&R (Artista e Repertório), que critica a música gerada e dá feedback estruturado.
• crewAI: framework de código aberto para orquestração de fluxos de trabalho multiagentes. Aqui, é usado para coordenar a pesquisa, composição musical e agentes de relatórios do Markdown.
• acp-sdk: o ACP-SDK foi desenvolvido pelo BeeAI para promover a interoperabilidade independente de framework em sistemas multiagentes. As referências e implementações são mantidas no repositório do ACP GitHub.
• Agent-Ops (opcional): uma plataforma de monitoramento e observabilidade para agentes de IA. Neste projeto, ele pode ser usado para rastrear o comportamento dos agentes e visualizar fluxos de trabalho multiagentes.

Este projeto demonstra um fluxo de trabalho multiagentes que mostra como o ACP (por meio do acp-sdk) pode agilizar a colaboração coerente e observável em todos os ecossistemas de agentes.

O fluxo de trabalho começa quando o usuário fornece uma URL. A partir daí, um sistema modular e independente de framework de agentes especializados transforma o conteúdo da página da web em um artefato criativo (uma música original) acompanhado por uma crítica de estilo profissional. Todos os componentes trabalham em conjunto para combinar essas saídas em um único relatório Markdown unificado e legível para seres humanos. Esse resultado final representa uma transformação completa dos dados originais, combinando geração criativa com insights analíticos.

Esse fluxo de trabalho de composição musical ilustra como o ACP permite que um sistema de IA agêntica multiagentes coordene a colaboração entre agentes desenvolvidos com dois frameworks distintos: BeeAI e crewAI, por servir como uma camada de comunicação compartilhada em todo o sistema.

Ao separar a comunicação da implementação, o sistema permanece modular e extensível, capaz de orquestrar agentes entre frameworks enquanto produz produções saídas coesas de ponta a ponta a partir de conteúdo da web não estruturado.

Agentes do ACP

Este projeto utiliza quatro agentes de IA especializados:

• Agente de pesquisa (crewAI): extrai temas e informações importantes da URL fornecida.
• Agente compositor musical (crewAI): gera uma música original com base na pesquisa.
• Agente de A&R (BeeAI): fornece uma crítica de estilo profissional à música, incluindo potencial de sucesso, pontos fortes, preocupações e recomendações.
• Agente de relatório do Markdown (crewAI): combina os dados de saída da equipe de redação da música e dos agentes de A&R e os formata em um relatório do Markdown limpo e legível.

Fluxo de trabalho do projeto de composição musical e crítica

1. O fluxo de trabalho começa quando o usuário envia uma URL por meio da aplicação do cliente. O cliente envia essa URL para o agente de pesquisa usando mensagens ACP, que então lê e analisa o conteúdo da página da web para extrair temas relevantes.
2. Em seguida, o agente compositor musical recebe os dados da pesquisa e compõe uma música original inspirada nos temas identificados no material de origem durante a análise. A música gerada é, então, enviada pelo ACP ao agente de A&R para crítica.
3. O agente A&R avalia a música, fornecendo feedback detalhado sobre seu potencial, pontos fortes e áreas para melhoria. Também pode identificar audiências, sugerir influências estilísticas e oferecer comparações com artistas ou gêneros semelhantes. Essa crítica, junto com a música, é encaminhada ao agente do relatório do Markdown.
4. Por fim, o agente de relatório do Markdown formata a música e a crítica em um relatório do Markdown limpo e legível, que é salvo e apresentado ao usuário.

Em todo o fluxo de trabalho, as mensagens trocadas entre agentes são estruturadas como objetos JSON enriquecidas com metadados. Esses metadados orientam a compreensão de cada agente sobre o conteúdo da mensagem, o contexto e as respostas esperadas.

Esse fluxo de trabalho demonstra um padrão reutilizável aplicável a qualquer caso de uso que exija a orquestração de pipelines de transformação de dados e análise multiagentes.

O ACP fornece um sistema de mensagens comum que permite que os agentes criados com diferentes frameworks troquem informações de maneira padronizada. Esse protocolo aberto permite que os agentes interoperem sem a necessidade de integrações personalizadas ou lógica interna compartilhada.

O cliente do ACP (acp-client.py ) é o orquestrador do fluxo de trabalho multiagentes. Ele coordena a comunicação entre o usuário e os agentes (crewAI e BeeAI) usando o ACP.

Visão geral do fluxo de trabalho do cliente do ACP

1. Prompt de entrada:
   • O cliente solicita que o usuário insira uma URL.
2. Enviar para o servidor do crewAI (porta 8000):
   • O cliente cria uma mensagem ACP contendo a URL e a envia para o servidor do crewAI em execução na porta 8000.
   • O servidor realiza a pesquisa e a composição musical, enviando as letras geradas de volta para o cliente como eventos do ACP transmitidos.
3. Envie para o servidor do BeeAI (porta 9000):
   • A música é enviada como uma mensagem ACP para o servidor do BeeAI na porta 9000.
   • O agente de A&R critica a música e retorna feedback, também por meio de eventos transmitidos.
4. Envie para o agente de relatórios do Markdown (servidor do crewAI, porta 8000):
   • O cliente empacota a música e a crítica em uma única mensagem e a envia de volta para o servidor do crewAI, onde o agente de relatórios do Markdown formata tudo em um relatório.
5. Salve a saída:
   • O cliente grava o relatório final do Markdown em um arquivo: a&r_feedback.md .

A acp-sdk  é a biblioteca principal que permite a comunicação padronizada dos agentes neste projeto.

Principais funções de acp-sdk :

• Estrutura da mensagem:
  • Garante que toda a comunicação seja estruturada e consistente (geralmente JSON com metadados).
  • A biblioteca implementa classes (Message, MessagePart) e tipos de eventos (MessagePartEvent, GenericEvent, MessageCompletedEvent)
• Comunicação com o cliente:
  • A classe Client é usada para se conectar aos servidores de agentes e enviar ou receber
    mensagens do ACP,
  • Compatível com streaming de respostas, para que os agentes possam enviar resultados parciais ou atualizações.
• Integração de servidor e agente:
  • Os agentes (no crewAI e BeeAI) são implementados como servidores compatíveis com ACP.
  • Expõem endpoints que aceitam mensagens do ACP e retornam eventos do ACP.

Exemplo de uso do cliente:

Estes são os requisitos do sistema para executar este projeto:

• Sistema operacional: macOS, Linux ou Windows
• Memória (RAM): >= 8 GB (recomendado: 16 GB ou mais, especialmente se executar LLMs locais com o Ollama)
• Espaço em disco: >= 5 GB de espaço livre (recomendado: 10 GB ou mais para executar o ambiente Python, quaisquer modelos locais e arquivos gerados)
  • Observação: se estiver usando o Ollama para LLMs locais, cada modelo pode exigir de 4 a 8 GB ou mais.
• Python: >= 3.11

Antes de começar, aqui está uma visão geral rápida das ferramentas e dos serviços de provedor de que você precisará.

A lista a seguir abrange os principais frameworks, plataformas e APIs necessários para o fluxo de trabalho multiagentes.

Nas seções subsequentes, você encontrará instruções passo a passo para instalar, configurar e usar cada ferramenta e provedor, para que você possa configurar seu ambiente.

• Gerenciador de pacotes UV: (gerenciador de pacotes Python baseado em Rust para gerenciamento de dependências)
• Plataforma e CLI do BeeAI: necessários para executar o servidor de agentes do BeeAI.
• crewAI: necessário para executar o servidor do crewAI e orquestrar tarefas
• Ollama: para executar LLMs locais (se o Ollama for o seu provedor selecionado)
• OpenRouter: chave de API necessária para usar o servidor de agentes pré-configurado do BeeAI
  • Observação: você pode mudar para outros provedores editando o arquivo .env e atualizando o código dos agentes, se necessário, ou por meio da CLI do BeeAI.
• IBM watsonx.ai: Chave de API (outro provedor opcional)
• Chave de API do AgentOps: opcional para rastreamento e monitoramento de agentes.
• Terminal ou IDE: um emulador de terminal ou ambiente de desenvolvimento integrado (IDE), como código VS (recomendado para gerenciar vários terminais e visualizar a saída do Markdown)

O BeeAI e o CrewAI são projetados para trabalhar com uma variedade de provedores de modelos de linguagem, tornando-os flexíveis para diferentes ambientes e casos de uso. In this tutorial, o OpenRouter é o provedor de LLMs para o agante do BeeAI, enquanto o Ollama ié usado para agentes do crewAI localmente.

Ambos os frameworks são independentes do provedor; portanto, você pode alternar para outros serviços de LLM atualizando as definições de configuração. Sua configuração pode variar dependendo do provedor de LLMs escolhido. Além disso, este tutorial inclui uma configuração opcional e pré-configurada para usar o IBM watsonx.ai como um provedor alternativo baseado na nuvem.

Você também pode usar seu provedor e modelo de LLM preferido; no entanto, observe que apenas as configurações mostradas neste tutorial foram testadas. Outros provedores e modelos podem exigir configuração ou ajustes adicionais.

Os seguintes requisitos são para os três provedores compatíveis com este projeto:

Você precisará de uma chave de API do OpenRouter para usar o servidor de agentes do BeeAI pré-configurado com modelos de linguagem baseados em nuvem.

Para usar o OpenRouter como seu provedor de LLMs para o agente do BeeAI, siga estas etapas:

1. Inscreva-se no OpenRouter
   • Acesse o OpenRouter e crie uma conta gratuita.
2. Gere uma chave de API
   • No dashboard do OpenRouter, gere uma nova chave de API.
3. Escolha um modelo
   • Navegue pela lista de modelos do OpenRouter e selecione um modelo que você deseja usar (por exemplo,deepseek/deepseek-r1-distill-llama-70b:free ).

Observação: o modelo gratuito pode ser diferente dependendo de quando este tutorial for executado. Para modelos gratuitos, confira a lista de modelos de pacote gratuito do OpenRouter.

Se você planeja usar o Ollama como seu provedor de LLMs para o agente do crewAI, siga estas etapas:

1.  Baixe e instale o Ollama
   • Acesse o Ollama e instale a aplicação para o seu sistema operacional.
2.  Inicie o servidor do Ollama
   • Em seu terminal, execute:
     ollama serve
3. Extraa um modelo
   • Baixe seu modelo específico (por exemplo, llama3):
     ollama pull llama3

Para usar o IBM watsonx.ai como seu provedor de LLMs para o servidor do crewAI, siga estas etapas:

1.  Faça login no watsonx.ai
   • Use sua conta do IBM® Cloud para fazer login no IBM Cloud.
2. Crie um projeto do watsonx.ai.
   • No dashboard do watsonx.ai, crie um novo projeto e salve o ID de seu projeto.
3.  Criar uma instância de serviço do watsonx.ai Runtime
   • Escolha o plano Lite (instância gratuita).
4.  Gere uma chave de API do watsonx
   • No IBM Cloud, acesse as configurações de sua conta e gere uma nova chave de API.
5.  Associe o serviço do watsonx.ai Runtime a seu projeto
   • No dashboard do watsonx.ai, vincule a instância do serviço do watsonx.ai Runtime ao projeto que você criou.

O IBM watsonx.ai é usado como um provedor de LLMs em nuvem opcional para agentes do crewAI neste tutorial.

O AgentOps é um serviço opcional para rastrear, monitorar e visualizar seus fluxos de trabalho multiagentes.
Se você quiser usar o AgentOps neste projeto, siga estas etapas:

1.  Inscreva-se no AgentOps
   • Acesse o AgentOps e crie uma conta gratuita.
2.  Gere uma chave de API
   • No dashboard do AgentOps, gere uma nova chave de API.
3.  Adicionar sua chave de API a seu arquivo .env 
   •  Exemplo de configuração:
     AGENTOPS_API_KEY=your_agentops_api_key
4.  Verifique a integração
   • Quando você executa seus agentes, os rastreios e logs devem aparecer no dashboard do AgentOps se a chave de API estiver definida corretamente.

O AgentOps não é necessário para executar o fluxo de trabalho, mas pode ajudar a monitorar a atividade dos agentes e depurar as interações multiagentes.

Para executar esse projeto, clone o repositório do GitHub usando https://github.com/IBM/ibmdotcom-tutorials.git como a URL HTTPS. Para ver etapas detalhadas sobre como clonar um repositório, consulte a documentação do GitHub.

Este tutorial pode ser encontrado dentro do diretório de projetos do repo.

Dentro de um terminal, navegue até o diretório deste tutorial:

Este projeto exige três scripts Python separados a serem executados simultaneamente para cada componente do sistema multiagentes. Consequentemente, você precisará abrir três janelas ou guias de terminal.

Comece mantendo o terminal atual aberto e, em seguida, abra mais dois terminais e certifique-se de que todos os três sejam direcionados para os diretórios corretos (conforme mostrado na próxima etapa).

Usando um IDE?

Se estiver usando um IDE como o Visual Studio Code*, você pode usar a funcionalidade Dividir terminal para gerenciar vários terminais lado a lado.

Caso contrário, abra três janelas de terminal independentes e navegue em cada uma até o subdiretório apropriado.

Navegação em terminais

Cada terminal é responsável por um dos seguintes componentes:

1. Terminal do cliente do ACP.
   Diretório: acp_tutorial
   
   cd acp_tutorial
   
   
2. Diretório de terminais do servidor de agentes do BeeAI:
    beeai_agent_server
   
   cd beeai_agent_server
   
   
3. Diretório de terminais do sistema d agentes do crewAI
   : crewai_agent_server
   
   cd crewai_agent_server
   
   

Cada componente é executado em seu próprio ambiente virtual para garantir um gerenciamento de dependências limpo. Este tutorial usa o  UV, um gerenciador de pacotes Python baseado no Rust para gerenciar e sincronizar ambientes.

Observação: certifique-se de que o Python 3.11 ou posterior esteja instalado antes de continuar.

Instale o UV

Se você ainda não o fez, instale o UV usando o Homebrew (recomendado para macOS e Linux):

Observação para usuários do Windows: instale o WSL (Subsistemas do Windows para Linux) e siga as instruções do Linux no seu terminal WSL.

Criar e ativar um ambiente virtual (em cada terminal)

Em cada terminal (BeeAI, CrewAI e cliente do ACP), execute o seguinte código:

Esta etapa criará e ativará uma .venv  no diretório atual

Em execução uv venv  dentro de cada diretório do projeto ajuda a isolar os ambientes por componente.

Agora instale dependências em cada terminal usando:

Essa etapa instala as dependências listadas no pyproject.toml  arquivo cada componente.

Com o BeeAI instalado, use o CLI para iniciar a plataforma BeeAI no beeai_agent_server :

Observação: na primeira execução, essa etapa pode levar vários minutos.

Configure seu provedor de LLM (OpenRouter)

Execute o seguinte comando para configurar o provedor e o modelo de LLM por meio da CLI interativa:

Siga os prompts para selecionar o OpenRouter e inserir sua chave de API e os detalhes do modelo.

Para confirmar suas configurações, use:

Essa etapa deve produzir seus configurados LLM_API_BASE , LLM_API_KEY, eLLM_MODEL .

Como alternativa, usuários avançados podem editar manualmente um .env  arquivo com os valores apropriados.

Exemplo de .env para o OpenRouter

Para verificar se o BeeAI está funcionando, envie um prompt de teste:

Uma resposta válida confirma que a plataforma está ativa.

Resolução de problemas

Se necessário, você pode atualizar ou reiniciar a plataforma:

No crewai_agent_server  diretório, crie um .env  arquivo copiando o modelo:

Aberto .env  e remova a marca de comentário da configuração do provedor de modelo de sua preferência. Este projeto é compatível com:

• Ollama (inferência local) ou
• IBM watsonx.ai (inferência em nuvem)

Você também pode personalizar seu próprio provedor usando os documentos de configuração do LLM do crewAI.

Atualize o código dos agentes do CrewAI

Em acp_crew.py , localize o llm = LLM (...)  bloqueie e remova a marca de comentário da seção apropriada para corresponder à sua .env  configuração.

Certifique-se de que os nomes das variáveis de ambiente em seus .env  arquivo correspondem ao que é esperado no código.

Depois que o BeeAI e o crewAI estiverem configurados, inicie os servidores dos agentes em seus respectivos terminais.

Inicie o servidor de agentes do BeeAI

No terminal beeai_agent_server :

Você deverá ver uma saída confirmando que o servidor foi iniciado em http://127.0.0.1:9000 , juntamente com verificações regulares de integridade:

O terminal deve registrar pings de integridade em intervalos de alguns segundos. Um 200 OK  status significa que o servidor está íntegro.

Inicie o servidor dos agentes do crewAI

No terminal crewai_agent_server :

Você deverá ver o servidor em execução em http://127.0.0.1:8000 , juntamente com 200 OK  logs.

Confirme se todos os agentes estão em execução

Agentes compatíveis com o ACP criados localmente são automaticamente reconhecidos pelo BeeAI. Use a CLI do BeeAI para confirmar s todos os agentes locais estão registrados e íntegros (esta etapa pode ser executada em qualquer terminal disponível):

Você deverá ver entradas para:

• artist-repertoire-agent (BeeAI, porta 9000)
• markdown_report_agent  (crewAI porta 8000)
• song_writer_agent  (crewAI porta 8000)

Se todos estiverem listados e acessíveis, poderemos confirmar que esses agentes foram interoperados com sucesso!

No terminal dedicado ao servidor acp-client (dentro do acp_tutorial  diretório):

Dentro do terminal, será solicitado que você insira uma URL. Essa entrada aciona o fluxo de trabalho multiagentes.

Com todos os agentes e o cliente/servidor em execução, você está pronto para iniciar o projeto do ACP!

1. Insira a URL que você quiser que os agentes processem. Por exemplo:
   
   URL: https://www.ibm.com/br-pt/think/topics/agent-communication-protocol
   
   
2. Você verá logs de status como:

1. O cliente envia a URL para o agente do crewAI, que pesquisa a página e gera o material para composição musical.
2. O agente do crewAI compõe uma música com base na pesquisa.
3. A música é enviada ao agente do BeeAI para crítica da A&R (Artista e Repertório).
4. O agente do BEEAI retorna feedback e sugestões estruturadas.
5. O cliente exibe a música gerada, a crítica e salva o feedback no a&r_feedback.md .

Observação: as saídas de grandes modelos de linguagem (LLMs) são probabilísticas e podem variar cada vez que você executa o fluxo de trabalho, mesmo com a mesma entrada.

Neste tutorial, você conectou dois frameworks multiagentes diferentes por meio de um cliente/servidor ACP, que expôs endpoints para os agentes de IA colaborarem para gerar e transformar dados. Ao separar a comunicação do comportamento do agente, o ACP permite que os agentes criados com o BeeAI, crewAI, LangChain e outros frameworks trabalhem juntos sem a necessidade de usar a lógica de integração personalizada. Essa abordagem melhora a modularidade, a escalabilidade e a interoperabilidade.

O ACP é uma iniciativa aberta impulsionada pela necessidade de os agentes enviarem, receberem e interpretarem mensagens. As mensagens no ACP são estruturadas, geralmente em formatos como JSON, e enriquecidas com metadados para garantir a consistência e a clareza nas interações dos agentes. Não importa se você está usando agentes com tecnologia OpenAI, Anthropic ou outros modelos de IA, o ACP fornece uma camada de mensagens compartilhada compatível com a interoperabilidade independente de framework.

Ao seguir esse fluxo de trabalho, você viu como agentes criativos e analíticos podem trabalhar em harmonia, transformando conteúdo não estruturado da web em uma música, crítica profissional e um relatório Markdown unificado. Essa abordagem demonstra o poder do ACP para permitir sistemas de IA multiagentes contínuos, escalável e flexíveis.

Quando você terminar de experimentar o sistema, siga estas etapas para encerrar corretamente todos os componentes em execução:

1. Interrompa todos os servidores em execução

Em cada janela de terminal, pressione Crtl + C  para parar o servidor. Esta etapa tenta um desligamento normal.

Você deverá ver a saída como:

2. Se o servidor travar durante o desligamento

Se um servidor deixar de responder ou travar ao ser desligado (por exemplo, preso em Waiting for application shutdown. ), você pode encerrar o processo manualmente:

Encontre a ID do processo (PID)

Execute o seguinte comando para localizar o processo do servidor:

Identifique a PID do processo que você está tentando interromper. Por exemplo:

Encerre o processo. Use a PID para pará-lo de forma forçada:

repita esse processo para cada servidor, se necessário.

É isso! Você executou com sucesso um sistema multiagentes completo entre plataformas usando o ACP.