使用 A2A 协议进行 AI 智能体通信

A2A，即 Agent2Agent 协议，是一个开放标准，支持 AI 智能体、客户端和工具之间进行结构化通信。本教程中，您可以构建一个智能体系统，其中聊天客户端处理用户查询，并将其发送到在符合 A2A 标准的服务器上运行的 AI 智能体。

大多数智能体 AI 应用程序在组件之间实现了自定义通信（例如 ChatDev 的 ChatChain），这使得很难在不同应用程序中复用同一智能体或集成外部工具。这种标准化的缺失阻碍了互操作性，并限制了更广泛的智能体生态系统的发展。

A2A 通过基于 HTTP、JSON-RPC 2.0 和服务器发送事件构建的标准化协议，将通信层与智能体逻辑分离，从而解决了这一限制。这种解耦使得智能体能够与其他智能体协作、服务客户端请求以及访问外部工具，而无需自定义集成代码。

A2A 支持去中心化架构，允许团队逐步演进其 AI 系统而不会破坏客户端代码。团队可以更新工具、交换模型或修改智能体行为，同时在复杂工作流中保持一致接口。

智能体以 JSON-RPC 格式结构化的消息交换信息，这些消息包含元数据，从而以清晰和一致的方式丰富了智能体交互。每个 A2A 服务器在一个已知端点 (.well-known/agent-card.json) 公开一个 AgentCard，将智能体的能力描述为结构化的 JSON 数据。因此，它允许客户端动态发现智能体的功能，类似于 API 文档描述可用端点的方式。

请按照步骤构建并运行一个 A2A 智能体系统，并获得以下方面的实践经验：

• BeeAI： 一个用于构建 AI 智能体的开源智能体框架。
• A2A 协议：用于智能体互操作性的标准化通信协议。
• Ollama： 用于在本地运行大型语言模型 (LLM) 的工具。
• 智能体工具：专用能力，包括网络搜索 (DuckDuckGo)、天气数据 (OpenMeteo)、维基百科访问 (WikipediaTool) 和推理 (ThinkTool)。

注意： 如果您使用过 ACP（智能体通信协议），您会发现相似之处。ACP 最初由 IBM 的 BeeAI 开发，现已与 Google A2A 在 Linux 基金会下开展合作。BeeAI 现在使用 A2A 适配器（A2AServer 和 A2AAgent）来提供符合 A2A 的通信。A2A 还与 MCP（模型上下文协议）协同工作，使智能体能够与数据源和工具交互，从而创建可互操作的智能体生态系统。

本项目演示了 A2A 如何实现客户端界面与智能体逻辑的清晰分离。

工作流遵循以下顺序：

1. 用户输入：客户端通过终端界面捕获用户输入。
2. A2A 请求：客户端将输入格式化为 JSON-RPC 消息有效负载，并将其发送到智能体服务器。
3. 智能体处理：服务器将请求转发给RequirementAgent ，它会分析任务，并根据需要执行适当的工具。
4. A2A 响应：服务器将智能体的响应作为 JSON-RPC 格式的结构化数据返回，并在结果生成时实时流式传输。
5. 显示：客户端在终端中提取并显示响应文本。

此工作流展示了一种可复用的模式，适用于需要结构化客户端-智能体通信的用例，例如具有工具编排功能的聊天机器人、任务自动化系统、客户支持智能体 和研究助手。

本项目使用一个具有多种工具能力的 AI 智能体。在更复杂的系统中，您可以部署多个专用智能体，每个智能体专注于特定领域或任务。

RequirementsAgent (BeeAI)：一个声明式智能体，能根据用户请求动态选择和协调多个工具。它使用以下工具：

• ThinkTool 用于推理和逻辑操作
• DuckDuckGoSearchTool 用于网络搜索
• OpenMeteoTool  用于获取天气数据
• WikipediaTool 用于信息检索

A2A 服务器（beeai-a2a-server/beeai_chat_server.py ) 通过 HTTP API 公开智能体功能。它承担三项关键职责：

1. LLM 初始化：通过 Ollama 加载本地语言模型

2. 智能体设置：创建一个 RequirementAgent，其中包含处理智能体生命周期的工具和内存

3. 服务器配置：通过符合 A2A 标准的 HTTP 端点公开智能体。

服务器自动在 /.well-known/agent-card.json 公开 AgentCard ，描述智能体的能力并有助于验证智能体配置。

A2A 客户端 (beeai-a2a-client/beeai_chat_client.py ）提供用户界面，并通过使用 A2A SDK 和 Python 的 asyncio 库进行异步消息处理来处理与服务器的通信。

连接设置：创建 A2A 客户端适配器

来自url 参数指定 A2A 兼容服务器的端点（默认值：http://127.0.0.1:9999 ）。现在memory 参数在本地存储对话历史记录，使客户端能够在交互过程中保持上下文并支持长时间运行的任务。

消息交换：发送异步提示并处理响应：

来自A2AAgent 是一个客户端适配器，抽象了 JSON-RPC 通信细节。它并非自主智能体，仅将用户输入转换为符合 A2A 标准的消息并处理服务器响应， 从而实现无缝的数据交换和可观测性。

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

• 操作系统：macOS、Linux 或 Windows
• 内存 (RAM)：>= 8 GB（推荐：16 GB 或更大，用于运行本地 LLM）
• 磁盘空间：>= 5GB 可用空间（ 推荐：10GB 或更大，以适应 Python 环境和本地模型）
• Python 版本：>=3.11

在开始之前，先来了解一下本项目所需的工具：

• BeeAI：：一个用于构建 AI 智能体的开源智能体开发工具包。BeeAI 支持包括 Ollama（本教程使用）、OpenAI 和 Anthropic 在内的多个 LLM 提供商。
• Ollama：用于运行本地 LLM，为 AI 智能体提供支持。
• A2A 协议： 已集成到 BeeAI 框架中，实现客户端与服务器间的结构化通信。
  
• 终端或 IDE：类似 Visual Studio Code 的终端或 IDE（推荐用于管理多个终端和查看日志）。
  
• Python 虚拟环境：用于隔离客户端和服务器的依赖项。

本项目使用 Ollama 作为 AI 智能体的模型提供um 。请按照以下步骤设置 Ollama：

1. 下载并安装 Ollama
   -     访问 Ollama 并为您的操作系统安装应用程序
2. 启动 Ollama 服务器 
   -   打开终端并运行：
   ollama serve
3. 拉取默认模型（需要大约 5 GB 磁盘空间）：
   
   ollama pull granite3.3:8b

注意：您可以通过设置环境变量，使用任何与 Ollama 兼容的模型BEEAI_MODEL 。检查 Ollama 模型库中可用的模型及其大小。

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

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

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

此项目需要同时运行两个独立的 Python 脚本，一个用于服务器，另一个用于客户端。您需要打开两个终端窗口或选项卡。

保持当前终端打开，然后打开第二个终端，并确保两者都已导航到正确的项目目录（a2a_tutorial 根目录）。

使用 IDE 吗？

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

否则，请打开两个独立的终端窗口，并导航到每个窗口的项目目录。

虚拟环境有助于保持依赖项的分离和维护。为了保持服务器和客户端依赖项的分离，为每个组件创建一个虚拟环境。

对于服务器：

导航至beeai-a2a-server 目录：

使用 Python 3.11 创建虚拟环境：

激活虚拟环境：

Windows 用户注意：使用 venv\Scripts\activate 激活虚拟环境。

对于客户：

导航至beeai-a2a-client 目录：

创建并激活虚拟环境：

通过在每个终端中运行以下代码，安装每个组件所需的依赖项：

您可以在终端中运行pip freeze 以验证环境及其依赖项是否已更新。

在第一个终端中，启动 A2A 智能体服务器：

您应该会看到：

服务器现在正在侦听来自客户端应用程序的传入请求，准备支持智能体之间的通信。

在另一个终端中，启动 A2A 客户端：  

这将提示您输入：

在客户终端中键入一条消息，然后按下Enter 。智能体程序处理您的查询并作出响应：

在服务器终端中，您可以查看 A2A 协议日志，其中显示了与推送通知的通信：

第一个请求检索描述智能体功能的 AgentCard。第二个请求将您的消息作为TextPart （A2A 消息中的文本内容单元）发送并接收响应。

注意：LLM 的输出具有概率性，即使输入相同，每次运行工作流时输出也可能有所不同。

尝试使用不同类型的查询来测试智能体的各种工具：

• 网络搜索：“搜索有关人工智能的最新新闻”
• 天气数据：“东京的天气怎么样？”
• 维基百科：“请介绍一下量子计算”
• 推理：“天空蔚蓝的三个原因是什么？”

请在浏览器中访问 https://0.0.0.0:9999/.well-known/agent-card.json，查看RequirementAgent 的 AgentCard。

此 JSON 文档介绍：

• 智能体的名称（RequirementAgent）及其功能的简要描述。
• 支持的通信协议和信息格式
• 任何要求或限制

此 AgentCard 允许任何符合 A2A 规范的客户端发现智能体并与之交互，而无需事先了解其实施细节。

在本教程中，您使用符合 A2A 标准的服务器构建了一个聊天系统，该服务器为客户端与智能体通信提供了一个结构化的接口。通过将消息层与内部逻辑分离，Agent2Agent 协议使团队能够在不更改客户端代码的情况下更新智能体功能、更换模型或修改工具配置。当协调需要输入的任务、跟踪任务状态或将每个操作视为一个独立的工作单元时， 这种灵活性尤其有价值。

A2A 的工作原理是定义任何兼容组件都能理解的通用消息格式， 允许自主智能体与其他智能体协作。该协议规范定义了如何采用 JSON-RPC 格式构建消息以及如何使用元数据进行丰富，确保交互中的一致性和清晰度。

本教程基于 A2A 示例存储库提供的基础示例构建。有关原始实现的更多信息，请参阅存储库中的自述文件，其中提供了构建符合 A2A 标准的系统的更多上下文和示例。

对于实际部署，A2A 服务器可以实现身份验证机制来保护智能体端点，使用服务器发送的事件进行流式响应，并可扩展以处理生产工作流。通过遵循此工作流，您可以了解命令行客户端如何通过标准化协议与 AI 智能体进行交互，从而使智能体能够协调多个工具并提供上下文响应。这种方法展示了 A2A 在启用可维护、可扩展和灵活的 AI 系统方面的强大功能。

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

在每个终端窗口中按下 Ctrl+C，可停止运行中的进程。

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

如果服务器没有响应或在关闭时挂起，您可以强行停止它：

查找进程 ID (PID)：

确定要停止的进程的 PID。

结束进程：

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

就这样。您已成功运行一个完整的符合 A2A 标准的聊天系统。