Multi-Agent Task Assistant with A2A & MCP-inspired Architecture

基于 A2A 和 MCP 的多 Agent 任务助手

本项目展示了一个多 Agent 系统，旨在处理文章起草和网络研究等任务。它采用自定义的 Agent-to-Agent（A2A）通信协议来协调各 Agent，并采用受模型上下文协议（MCP）启发的架构来与外部工具服务交互。系统使用 Python、Langchain、Anthropic 大模型、FastAPI 和 Docker 构建。

概览

任务助手允许用户请求起草特定主题的文章或开展网络研究。用户输入首先由“Supervisor LLM”验证和处理。验证通过的任务随后由 Task Manager Agent 管理，它会将子任务分配给专门的 Agent：Article Draft Agent 和 Researcher Agent。这些 Agent 通过专用的“MCP 工具服务”使用外部能力（如大模型文本生成、网络搜索和云存储）。Streamlit 应用提供用户界面。

• 系统已调整为支持任意语言输入，并以英语输出。

点击此处查看系统使用示例。

重要：Google Cloud 身份验证（google_credentials.json）

若要让 Cloud Storage MCP Server 与 Google Cloud Storage 交互，需要设置服务账号并提供其 JSON 密钥：

1. 创建服务账号： 在 Google Cloud Platform（GCP）项目中创建一个新的服务账号。
2. 授予权限： 为此服务账号分配必要的角色或权限，使其能够对目标 GCS 存储桶进行读写操作（例如，“Storage Object Admin”，或在指定存储桶上授予更精细的权限，如“Storage Object Creator”和“Storage Object Viewer”）。
3. 生成 JSON 密钥： 为此服务账号创建 JSON 密钥并下载。
4. 放置并重命名密钥： 将下载的 JSON 密钥文件放在本项目的根目录中，并将其重命名为 google_credentials.json。

⚠️ 安全提示： google_credentials.json 文件包含敏感凭据。请确保绝不将其提交到版本控制系统中（例如，如果 .gitignore 文件中尚未列出该文件，请将其添加进去）。docker-compose.yml 文件已配置为将此文件从项目根目录挂载到 cloud-storage-mcp 服务中。

系统架构

功能

• 文章起草： 根据给定的主题和风格生成文章草稿，然后将其保存到 Google Cloud Storage，并提供公开 URL。
• 网络研究： 针对某个主题进行模拟网络研究，并返回经过总结的发现列表。
• Supervisor LLM 输入验证： 在将用户输入分配给 Agent 之前，由大模型对其进行预处理、安全性验证，并翻译成英语。
• Agent-to-Agent（A2A）通信： 自定义协议，供 Agent 分配任务、发送状态更新和返回结果。
• 受模型上下文协议（MCP）启发的工具机制： 专门的服务通过类似 MCP 的请求/响应模式提供工具（大模型生成、Cloud Storage、Web Search）。
• 异步任务处理： 任务以异步方式处理，界面会轮询状态更新。
• 微服务架构： 使用 Docker 将组件容器化，并通过 Docker Compose 进行编排。

LLM 模型用法

本项目使用多个 Anthropic Claude 模型来实现不同功能：

• 监督 LLM（输入验证与处理）：

  • 模型： claude-3-7-sonnet-20250219
  • 组件： 由 Streamlit UI（ui/streamlit/app.py）直接调用。
  • 用途： 在分配任务前验证、清理用户输入（主题、风格）、检查其中是否包含有害内容、识别语言并将其翻译成英语。

• 文章起草 Agent（核心 Agent 逻辑）：

  • 模型： claude-3-haiku-20240307
  • 组件： agents/article_draft/main.py
  • 用途： 驱动 Langchain Agent 的决策过程（例如，确定要使用哪个工具、如何安排操作顺序，以及根据工具输出撰写最终回复）。

• 研究 Agent（核心 Agent 逻辑）：

  • 模型： claude-3-haiku-20240307
  • 组件： agents/researcher/main.py
  • 用途： 驱动 Langchain Agent 执行研究任务，并总结 search_web 工具的搜索结果。

• 创意 LLM MCP 服务（文本生成工具）：

  • 模型： claude-3-5-sonnet-20241022
  • 组件： mcp_servers/creative_llm/main.py
  • 用途： 提供 generate_text 工具，供 文章起草 Agent 用于生成文章内容。

• 网页搜索 MCP 服务（模拟网页搜索工具）：

  • 模型： claude-3-haiku-20240307
  • 组件： mcp_servers/web_search/main.py
  • 用途： 提供 search_web 工具，供 研究 Agent 根据查询生成模拟搜索结果。

注意：任务管理 Agent 和 云存储 MCP 服务 的核心操作不会直接使用 LLM。

架构

系统由以下关键组件组成：

1. Streamlit UI（streamlit-ui）： 用户提交任务和查看结果的 Web 界面。它还会调用 Supervisor 大模型。
2. Supervisor 大模型（外部调用）： 由 UI 直接调用的 Anthropic Claude 模型，用于验证、清理和翻译用户输入。
3. 任务管理器 Agent（task-manager）：
   • 接收 UI 传来的已验证任务。
   • 使用 A2A 协议将任务分配给相应的工作 Agent。
   • 跟踪任务状态并向 UI 提供更新。
   • 通过 A2A 协议接收工作 Agent 返回的结果。
4. 工作 Agent：
   • 文章草稿 Agent（article-draft-agent）： 一个 Langchain Agent，负责生成文章内容（使用 Creative LLM MCP 服务），并上传内容（使用 Cloud Storage MCP 服务）。
   • 研究员 Agent（researcher）： 一个 Langchain Agent，负责开展研究（使用 Web Search MCP 服务）。
5. MCP 工具服务：
   • Creative LLM MCP 服务（creative-llm-mcp）： 提供由 Anthropic 大模型驱动的 generate_text 工具。
   • Cloud Storage MCP 服务（cloud-storage-mcp）： 为 Google Cloud Storage 提供 upload_file、download_file 和 delete_file 工具。
   • Web Search MCP 服务（web-search-mcp）： 提供 search_web 工具，使用 Anthropic 大模型模拟网络搜索结果。
6. 通信协议：
   • 自定义 A2A 协议： 定义于 protocols/messages.py（例如 A2AMessage、A2APayloadAssignTask），用于任务管理器与工作 Agent 之间通过 HTTP 通信。
   • 受 MCP 启发的自定义协议： 定义于 protocols/messages.py（例如 MCPToolCall、MCPToolResult），由 Langchain 工具通过 tools/mcp_tool_adapter.py 使用，以通过 HTTP 与 MCP 工具服务通信。

高级流程（文章任务示例）：

1. 用户通过 Streamlit UI 提交文章主题／风格。
2. UI 调用 Supervisor 大模型来验证和处理输入。
3. 如果获批，UI 会向 task-manager Agent 发送请求。
4. task-manager 将“write_article_draft”任务分配给 article-draft-agent（A2A）。
5. article-draft-agent 使用其 generate_text_tool。
   • 该工具调用 creative-llm-mcp 服务（MCP）生成文章内容。
6. 随后，article-draft-agent 使用其 upload_file_tool。
   • 该工具调用 cloud-storage-mcp 服务（MCP）上传内容并获取公开 URL。
7. article-draft-agent 将公开 URL 发回 task-manager（A2A）。
8. UI 轮询 task-manager 以获取状态，取回 URL、获取内容并显示。

使用的核心技术

• Python 3.9
• 框架与库：
  • FastAPI：用于构建 Agent 和 MCP 服务 API。
  • Uvicorn：FastAPI 的 ASGI 服务端。
  • Langchain 与 Langchain-Anthropic：用于构建由大模型驱动的 Agent 和工具。
  • Anthropic Python SDK：用于 Supervisor 大模型和大模型工具。
  • Pydantic：用于协议中的数据验证和设置管理。
  • Streamlit：用于用户界面。
  • Requests：用于 HTTP 通信。
  • Google Cloud Storage SDK（google-cloud-storage）：用于文件存储。
• 容器化：
  • Docker
  • Docker Compose
• 云服务：
  • Anthropic API（Claude 模型）
  • Google Cloud Storage

项目结构

├── agents/
│   ├── article_draft/
│   │   ├── Dockerfile
│   │   └── main.py
│   ├── researcher/
│   │   ├── Dockerfile
│   │   └── main.py
│   └── task_manager/
│       ├── Dockerfile
│       └── main.py
├── mcp_servers/
│   ├── cloud_storage/
│   │   ├── Dockerfile
│   │   └── main.py
│   ├── creative_llm/
│   │   ├── Dockerfile
│   │   ├── main.py
│   └── web_search/
│       ├── Dockerfile
│       └── main.py
├── protocols/
│   └── messages.py       # Pydantic models for A2A and MCP communication
├── tools/
│   ├── generate_text_tool.py
│   ├── mcp_tool_adapter.py # Client for calling MCP tool servers
│   ├── research_tool.py
│   └── upload_file_tool.py
├── ui/
│   └── streamlit/
│       ├── Dockerfile
│       ├── app.py
│       └── requirements.txt
├── .env                    # For API keys and environment variables (create this)
├── config.py               # Internal service URLs
├── docker-compose.yml      # Docker Compose orchestration
└── google_credentials.json # Google Cloud service account key (create this)

前提条件

• 已安装 Docker 和 Docker Compose。
• Anthropic API 密钥。
• 一个 Google Cloud 项目，且具备以下条件：
  • 已启用 Google Cloud Storage API。
  • 已创建 GCS 存储桶。
  • 有一个具备 GCS 存储桶写入权限的服务账号密钥（google_credentials.json）。

设置与运行项目

1. 克隆仓库（示例）：

   git clone https://github.com/ogulcanakca/article-assistant
   cd article-assistant
   

2. 创建 .env 文件： 在项目根目录中创建一个 .env 文件，并添加凭据和配置：

   ANTHROPIC_API_KEY="sk-ant-..."
   GOOGLE_API_KEY="AIzaSy..." # If needed by any other Google service, otherwise can be omitted if only GCS is used via service account
   GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
   CLOUD_STORAGE_BUCKET_NAME="your-gcs-bucket-name" # Used by article_draft_agent
   

   • CLOUD_STORAGE_BUCKET_NAME 是用于存储文章的 GCS 存储桶名称。

3. 添加 Google Cloud 凭据： 将下载的 Google Cloud 服务账号密钥文件放在项目根目录中，并命名为 google_credentials.json。docker-compose.yml 会将此文件挂载到 cloud-storage-mcp 服务中。

4. 为每个服务创建 requirements.txt： 确保每个服务目录（agents/*、mcp_servers/*、ui/streamlit）都有自己的 requirements.txt 文件，其中列出相应的 Python 依赖项。例如：

   • agents/article_draft/requirements.txt：

     fastapi
     uvicorn
     langchain
     langchain-anthropic
     requests
     # pydantic is usually a transitive dependency of FastAPI/Langchain
     

   • mcp_servers/cloud_storage/requirements.txt：

     fastapi
     uvicorn
     google-cloud-storage
     requests
     

   • ui/streamlit/requirements.txt：

     streamlit
     requests
     anthropic
     

   *（根据每个 main.py 文件中的实际导入内容调整这些列表。）

5. 使用 Docker Compose 构建并运行： 在项目根目录中运行：

   docker-compose up --build
   

6. 访问 UI： 服务启动并运行后，打开 Web 浏览器并访问： http://localhost:8501

7. 停止服务：

   docker-compose down
   

注意事项

• web-search-mcp 服务目前使用大模型模拟网络搜索结果，不会执行实时网络搜索。
• 确保在 .env 文件中正确设置所有必要的环境变量（尤其是 API 密钥和 GCS 存储桶名称），并通过 docker-compose.yml 将其传递给相应的服务。
• .env 中的 GOOGLE_API_KEY 仅为完整起见而列出，以备其他 Google 服务直接使用 API 密钥。对于 Google Cloud Storage，cloud-storage-mcp 服务主要使用 google_credentials.json 服务账号进行身份验证。

任务 1 和任务 2 示例