使用 ACP 实现 AI 智能体互操作性：构建多智能体工作流

在本教程中，您将使用 智能体通信协议 (ACP) 来深入了解 多智能体、跨平台 AI 工作流，展示 BeeAI 和 crewAI 的实时智能体协作。ACP 作为一个共享的开放标准消息传递层，来自不同框架的智能体能够无需自定义集成逻辑即可进行通信和协调。

ACP 对于企业 AI 环境尤其有价值，其中团队通常需要跨不同平台、工具和基础架构构建智能体和工作流。通过提供标准化的消息传递层，ACP 可实现可扩展、安全和模块化的智能体协作，从而满足现代企业 AI 系统的需求。

此项目通过使 AI 驱动的智能体能够跨越框架孤岛进行协作，将研究、内容生成和反馈等智能体功能整合到一个统一的工作流中，展示智能体的互操作性。

大多数 智能体式 AI 框架都使用自定义或封闭系统来处理通信。这种架构使得跨工具链、团队或基础设施连接智能体变得困难，尤其是在组合来自不同 AI 系统的组件时。

ACP 引入了一个标准化、与框架无关的消息格式，用于自主智能体发送、接收和解释消息。消息通常以 JSON 格式结构化，并包含元数据，以增强智能体交互的清晰度和一致性。

通过将通信与智能体的内部逻辑分离，ACP 允许团队混合和匹配使用不同的 AI 智能体框架，例如 BeeAI、 CrewAI、 LangChain 或 LangGraph，而无需自定义集成代码。这种方法提高了可扩展性，简化了自动化，并支持符合现代行业标准的模块化、透明系统设计。

在本教程结束时，您将看到 ACP 的实际示例，并获得使用以下技术的实践经验：

• BeeAI： 一个用于构建和管理 AI 智能体的灵活框架。在此项目中，它用于运行 A&R (Artist & Repertoire) 智能体，对生成的歌曲进行点评并提供结构化反馈。
• crewAI： 一个用于编排多智能体工作流的开源框架。在此项目中，它用于协调研究、歌曲创作和 Markdown 报告智能体。
• acp-sdk： ACP-SDK 由 BeeAI 开发，旨在促进多智能体系统之间独立于框架的互操作性。引用和实现在 ACP GitHub 存储库下维护。
• Agent-Ops（可选）： 一个用于 AI 智能体的监控和可观测性平台。在此项目中，它可用于跟踪智能体行为并可视化多智能体工作流。

此项目演示了多智能体工作流，展示 ACP（通过 acp-sdk）如何简化跨生态系统的连贯且可观察的协作。

当用户提供 URL 时，工作流启动。在此基础上，一个独立于框架的模块化专业智能体系统会将网页内容转化为创意作品，即一首原创歌曲，并附上专业风格的评论。所有组件协同工作，将这些输出组合成一个统一的人类可读的 Markdown 报告。这个最终结果代表了原始数据的完整转化，将创意生成与分析洞察相结合。

此歌曲创作工作流展示了 ACP 如何作为一个共享的通信层，使一个多智能体、智能体式 AI 系统能够协调两个不同框架（BeeAI 和 crewAI）开发的智能体之间的协作。

通过将通信与实现分离，该系统保持模块化和可扩展性——能够在框架之间协调智能体，同时从非结构化的网络内容产生连贯的端到端输出。

ACP 智能体

此项目使用了四个专门的 AI 智能体：

• 研究智能体 (crewAI)： 从提供的 URL 中提取主题和关键信息。
• 歌曲创作智能体 (crewAI)：根据研究生成原创歌曲。
• A&R 智能体 (BeeAI)：提供专业风格的歌曲评论，包括热门歌曲的潜力、优势、关注点和建议。
• Markdown 报告智能体 (crewAI)： 将歌曲创作团队和 A&R 智能体的输出数据相结合，并将其格式转换为简洁、可读的 Markdown 报告。

歌曲创作和评论项目工作流

1. 当用户通过客户端应用程序提交 URL 时，工作流启动。客户端使用 ACP 消息将此 URL 发送给研究智能体，然后研究智能体读取并分析网页内容以提取相关主题。
2. 接下来，歌曲创作智能体接收研究数据，并根据分析过程中从源材料中识别的主题创作一首原创歌曲。然后，ACP 将生成的歌曲发送给 A&R 智能体进行评论。
3. A&R 智能体对歌曲进行评估，提供关于其潜力、优势和改进领域的详细反馈。它还可以识别目标受众，建议风格影响因素，并提供与类似艺术家或流派的比较。这些评论与歌曲一起转发给 Markdown 报告智能体。
4. 最后，Markdown 报告智能体将歌曲和评论格式化为一份清晰、可读的 Markdown 报告，将其保存和呈现给用户。

在整个工作流中，智能体之间交换的消息被结构化为带有丰富元数据的 JSON 对象。这些元数据指导每个智能体对消息内容、上下文和预期响应的理解。

此工作流展示了一个可重用的模式，适用于任何需要协调多智能体数据转换和分析管道的用例。

ACP 提供了一个通用消息传递系统，允许使用不同框架构建的智能体以标准化的方式交换信息。这种开放协议允许智能体无需自定义集成或共享内部逻辑即可互操作。

ACP 客户端 (acp-client.py ) 是多智能体工作流的协调器。它使用 ACP 协调用户和智能体（crewAI 和 BeeAI）之间的通信。

ACP 客户工作流概述

1. 提示输入：
   • 客户端要求用户输入 URL。
2. 发送到 crewAI 服务器（端口 8000）：
   • 客户端构建一条包含该 URL 的 ACP 消息，并将其发送到在端口 8000 上运行的 crewAI 服务器。
   • 服务器执行研究和歌曲创作，并将生成的歌词作为流式 ACP 事件发送回客户端。
3. 发送到 BeeAI 服务器（端口 9000）：
   • 歌曲将作为 ACP 消息发送到在端口 9000 上运行的 BeeAI 服务器。
   • A&R 智能体对歌曲进行评论，并通过流式事件返回反馈。
4. 发送到 Markdown 报告智能体（crewAI 服务器，端口 8000）：
   • 客户端将歌曲和评论打包成一条消息，并将其发送回 crewAI 服务器，Markdown 报告智能体会将所有内容格式化为一份报告。
5. 保存输出：
   • 客户端将最终的 Markdown 报告写入文件： a&r_feedback.md .

然后，acp-sdk  是此项目中实现标准化智能体通信的核心库。

 的关键角色acp-sdk :

• 消息结构：
  • 确保所有通信都是结构化且一致的（通常是带有元数据的 JSON）。
  • 该库实现了类（Message、 MessagePart）和事件类型（MessagePartEvent、 GenericEvent、 MessageCompletedEvent）。
• 客户通信：
  •  客户端 类用于连接智能体服务器并发送或接收
    ACP 信息。
  • 支持流式响应，以便智能体可以发送部分结果或更新。
• 智能体服务器集成：
  • 智能体（在crewAI 和 BeeAI 中）被实现为符合 ACP 标准的服务器。
  • 它们公开接受 ACP 消息并返回 ACP 事件的端点。

客户端使用示例：

以下是运行此项目的系统要求：

• 操作系统： macOS、Linux 或 Windows
• 内存（RAM）： ≥ 8 GB（建议： 16 GB 或更多，尤其是使用 Ollama 运行本地 LLM）
• 磁盘空间： >= 5 GB 可用空间（建议：10 GB 或更多，用于运行 Python 环境、任何本地模型和生成的文件）
  • 注意： 如果使用 Ollama 运行本地 LLM，每个模型可能需要 4-8 GB 或更多内存。
• Python： >= 3.11

在开始之前，以下是您需要的工具和提供程序服务的快速概述。

以下列表涵盖了多智能体工作流所需的主要框架、平台和 API。

在随后的部分中，您将找到有关安装、配置和使用每个工具和提供程序的逐步说明，以便您可以设置环境。

• UV 包管理器：（基于 Rust 的 Python 包管理器，用于依赖项管理）
• BeeAI Platform 和 CLI： 运行 BeeAI 智能体服务器所需
• crewAI： 运行 crewAI 服务器和 Orchestrate 任务所需
• Ollama： 用于运行本地 LLM（如果 Ollama 是您选择的提供程序）
• OpenRouter： 使用预配置的 BeeAI 智能体服务器需要 API 密钥
  • 注： 您可以通过编辑 .env 文件并更新智能体代码（如有需要），或通过 BeeAI CLI 切换到其他提供程序。
• IBM watsonx.ai: API 密钥（另一个可选提供程序）
• AgentOps API 密钥： 用于智能体跟踪和监控的可选项。
• 终端或 IDE： 终端仿真器或集成开发环境 (IDE)，如 VS code（建议用于管理多个终端和查看 Markdown 输出）。

BeeAI 和 crewAI 均可与各种语言模型提供程序协同工作，从而灵活地适用于不同的环境和用例。在本教程中，OpenRouter 是 BeeAI 智能体的 LLM 提供程序，而 Ollama 用于本地的 crewAI 智能体。

这两个框架均独立于提供程序，因此您可通过更新配置设置来切换到其他 LLM 服务。您的设置可能会因所选择的 LLM 提供程序而异。此外，本教程还包括一个可选的预配置设置，以便使用 IBM watsonx.ai 作为替代的基于云的提供程序。

您也可以使用个人首选的 LLM 提供程序和模式；但请注意，只有本教程中显示的配置已经过测试。其他提供程序和模型可能需要额外的设置或调整。

以下要求适用于此项目中支持的三个提供程序：

您需要一个 OpenRouter API 密钥，才能使用预配置的 BeeAI 智能体服务器与基于云的语言模型。

要将 OpenRouter 作为 BeeAI 智能体的 LLM 提供程序，请按照以下步骤操作：

1. 注册 OpenRouter
   • 转到 OpenRouter 并创建一个免费帐户。
2. 生成 API 密钥
   • 在 OpenRouter 仪表板中，生成新的 API 密钥。
3. 选择模型
   • 浏览 OpenRouter 模型列表 并选择要使用的模型（例如，deepseek/deepseek-r1-distill-llama-70b:free ).

注意：根据本教程运行的时间，免费模型可能会有所不同。对于免费模型，请查看  OpenRouter 免费套餐模型列表。

如果您计划使用 Ollama 作为 crewAI 智能体的 LLM 提供程序，请按照以下步骤操作：

1.  下载并安装 Ollama
   • 访问 Ollama 并为您的操作系统安装应用程序。
2.  启动 Ollama 服务器
   • 在您的终端中运行：
     ollama serve
3. 拉取模型
   • 下载您的特定模型（例如 llama3）：
     ollama pull llama3

要使用 IBM watsonx.ai 作为 crewAI 服务器的 LLM 提供程序，请按照以下步骤操作：

1.  使用您的 IBM Cloud 帐户登录 watsonx.ai
   • 使用您的 IBM Cloud 帐户登录 IBM Cloud。
2. 创建 watsonx.ai 项目
   • 在 watsonx.ai 仪表板中，创建一个新项目并保存项目 ID。
3.  创建 watsonx.ai 运行时服务实例
   • 选择 Lite 套餐（免费实例）。
4.  生成 watsonx API 密钥
   • 在 IBM Cloud 中，转到您的帐户设置并生成新的 API 密钥。
5.  将 watsonx.ai 运行时服务关联到您的项目
   • 在 watsonx.ai 仪表板中，将运行时服务实例链接到您创建的项目。

在本教程中，使用 IBM watsonx.ai 作为 crewAI 智能体的可选云 LLM 提供程序。

AgentOps 是一项可选服务，用于跟踪、监控和可视化您的多智能体工作流。
如果您想在此项目中使用 AgentOps，请按照以下步骤操作：

1.  注册 AgentOps
   • 转到 AgentOps 并创建一个免费帐户。
2.  生成 API 密钥
   • 在 AgentOps 仪表板中，生成新的 API 密钥。
3.  将 API 密钥添加到 .env 文件
   •  配置示例：
     AGENTOPS_API_KEY=your_agentops_api_key
4.  验证集成
   • 当您运行智能体时，如果 API 密钥设置正确，跟踪和日志应出现在 AgentOps 仪表板中。

AgentOps不是运行工作流所必需的，但它可以帮助您监控智能体活动并调试多智能体交互。

要运行此项目，请使用 https://github.com/IBM/ibmdotcom-tutorials.git  作为 HTTPS URL 克隆GitHub 存储库。有关如何克隆存储库的详细步骤，请参阅 GitHub 文档。

本教程可以在 存储库的项目目录中找到。

在终端中，导航到本教程的目录：

此项目需要为多智能体系统的每个组件同时运行 三个独立的 Python 脚本 。因此，您需要打开三个终端窗口或标签页。

首先保持当前终端打开，然后打开 另外两个终端，并确保所有三个都已导航到正确的目录（如下一步所示）。

使用 IDE 吗？

如果您使用的是类似 Visual Studio Code 的 IDE * ，可以使用拆分终端功能并排管理多个终端。

否则打开三个独立的终端窗口，并将每个窗口导航到正确的子目录。

终端导航

每个终端负责以下组件之一：

1. ACP 客户端终端。
   目录： acp_tutorial
   
   cd acp_tutorial
   
   
2. BeeAI 智能体服务器终端
   目录： beeai_gent_server
   
   cd beeai_agent_server
   
   
3. crewAI 智能体系统终端
   目录： crewai_gent_server
   
   cd crewai_agent_server
   
   

每个组件都在自己的虚拟环境中运行，以确保明确的依赖项管理。本教程使用基于 Rust 的 Python 包管理器 UV 来管理和同步环境。

注意：在继续之前，请确保已安装 Python 3.11 或更高版本。

安装 UV

如果尚未安装，请使用 Homebrew 安装 UV（建议用于 macOS 和 Linux）：

Windows 用户注意事项： 安装 WSL（适用于 Linux 的 Windows 子系统） 并按照 WSL 终端中的 Linux 说明进行操作。

创建并激活虚拟环境（在每个终端中）

在每个终端（BeeAI、crewAI 和 ACP 客户端）中运行以下代码：

此步骤将在当前目录中创建并激活一个 .venv  

在每个项目目录中运行 uv venv  有助于按组件隔离环境。

现在使用以下方法在 每个终端 中安装依赖项：

此步骤将安装每个组件的 pyproject.toml  文件中列出的依赖项。

BeeAI 安装后，使用 CLI 启动 BeeAI 平台 beeai_agent_server :

注意：首次运行时，此步骤可能需要几分钟。

设置 LLM 提供程序 (OpenRouter)

运行以下命令，通过交互式 CLI 配置 LLM 提供程序和模型：

按照提示选择 OpenRouter，并输入您的 API 密钥和模型详细信息。

要确认您的设置，请使用：

此步骤应输出您配置的内容 LLM_API_BASE , LLM_API_KEY, 和LLM_MODEL .

或者，高级用户可以手动编辑 .env  文件，添加适当的值。

OpenRouter 的 .env 示例

如需验证 BeeAI 是否正在运行，请发送测试提示：

有效响应确认平台处于活动状态。

故障诊断

如有需要，您可以更新或重新启动平台：

在 crewai_agent_server  目录下，通过复制模板创建一个.env  文件：

打开 .env  并取消注释您首选的模型提供程序配置。此项目支持：

• Ollama（本地推理），或
• IBM watsonx.ai（云推理）

您还可以使用 crewAI LLM 配置文档自定义自己的提供程序。

更新 crewAI 智能体代码

在 acp_crew.py ，找到 llm = LLM (...)  屏蔽并取消对相应部分的注释，以匹配您的.env  配置。

确保您的 .env  文件中的环境变量名称与代码中预期的名称一致。

配置 BeeAI 和 crewAI 后，在各自的终端中启动智能体服务器。

启动 BeeAI 智能体服务器

在 beeai_agent_server 终端中：

您应该看到确认服务器已在 http://127.0.0.1:9000 上启动的输出，以及定期的运行状况检查：

终端应每隔几秒钟记录一次运行状况检查 ping 值。 200 OK  状态表示服务器运行正常。

启动 crewAI 智能体服务器

在 crewai_agent_server 终端中：

您应该看到服务器在 http://127.0.0.1:8000 上运行，以及 200 OK  日志。

确认所有智能体都在运行

本地构建的符合 ACP 标准的智能体由 BeeAI 自动识别。使用 BeeAI CLI 确认所有本地智能体均已注册且运行状况良好（此步骤可以在任意空闲终端中运行）：

您将看到以下条目：

• artist-repertoire-agent （BeeAI，端口 9000）
• markdown_report_agent  （crewAI 端口 8000）
• song_writer_agent  （crewAI 端口 8000）

如果所有智能体都已列出且可访问，我们可以确认这些智能体已成功实现互操作！

在专用于 acp-client 服务器的终端中（在 acp_tutorial  目录）：

在终端内，系统将提示您输入 URL。此输入触发多智能体工作流。

所有智能体和客户端/服务器都运行正常后，就可以启动 ACP 项目了！

1. 输入您希望智能体处理的任意 URL。例如：
   
   URL: https://www.ibm.com/cn-zh/think/topics/agent-communication-protocol
   
   
2. 您将看到类似以下的状态日志：

1. 客户端将 URL 发送到 crewAI 智能体，该智能体会搜索页面并生成歌曲创作素材。
2. crewAI 智能体根据研究结果创作歌曲。
3. 歌曲被发送到 BeeAI 智能体进行 A&R (Artist & Repertoire) 评论。
4. BeeAI 智能体返回结构化的反馈和建议。
5. 客户端会显示生成的歌曲和评论，并将反馈保存到 a&r_feedback.md .

注意： 大语言模型（LLM）的输出是概率性的，即使输入相同，每次运行工作流时输出也可能不同。

在本教程中，您通过一个 ACP 客户端/服务器连接两个不同的多智能体框架，该客户端/服务器提供了端点，供 AI 智能体协作生成和转换数据。通过将通信与智能体行为分开，ACP 使得使用 BeeAI、crewAI、LangChain 和其他智能体框架构建的智能体可以协同工作，而无需自定义集成逻辑。这种方法提高了模块化、可扩展性和互操作性。

ACP是一个开放的倡议，由智能体发送、接收和解释消息的需求驱动。ACP 中的消息是结构化的，通常采用 JSON 等格式，并富含元数据，以确保智能体交互之间的一致性和清晰度。无论您使用的是由 OpenAI、Anthropic 或是其他 AI 模型驱动的智能体，ACP 都能为不依赖框架的互操作性提供共享消息传递层。

通过遵循此工作流，您已经看到创意和分析智能体如何协调工作，将非结构化网络内容转换为歌曲、专业评论和统一的 Markdown 报告。这种方法展现了 ACP 在实现无缝、可扩展和灵活的多智能体 AI 系统方面的强大功能。

完成系统试验后，请按照以下步骤彻底关闭所有正在运行的组件：

1. 停止每个运行中的服务器

在 每个终端窗口中，按下 Crtl + C  以停止服务器。此步骤尝试优雅关机。

您应该看到类似以下内容的输出：

2. 如果服务器在关闭期间挂起

如果服务器在关机时没有响应或挂起（例如卡在 Waiting for application shutdown. ），则可以手动终止该进程：

查找进程 ID (PID)

运行以下命令来找到服务器进程：

确定要停止的进程的 PID。例如：

终止进程。 使用 PID 强制停止该进程：

如有必要，请对每个服务器重复此过程。

就这样！您已使用 ACP 成功运行一个完整的跨平台多智能体系统。