225 lines
8.0 KiB
Markdown
225 lines
8.0 KiB
Markdown
# A2A 平台建设计划
|
||
|
||
> 基于 ADK + MCP 的主从式智能体平台
|
||
> 主控：CodeBuddy ｜ 第一个子 Agent：全栈代码开发辅助
|
||
|
||
---
|
||
|
||
## 一、项目背景与目标
|
||
|
||
### 1.1 背景
|
||
- 使用 ADK (Agent Development Kit) 搭建子智能体
|
||
- 通过 LiteLlm 连接第三方 vLLM 端点：`https://9router.aqroid.cn/v1`
|
||
- 模型：`gikun1/gpt-5.6-luna`（OpenAI 兼容接口）
|
||
- **CodeBuddy 作为主控**，用户通过 CodeBuddy 调度子 agent 完成任务
|
||
|
||
### 1.2 目标
|
||
搭建主从式 A2A (Agent-to-Agent) 平台，支持：
|
||
- 用户只跟 CodeBuddy 交互，由 CodeBuddy 调度子 agent 执行具体任务
|
||
- 子 agent 通过 MCP HTTP 接口对外提供服务
|
||
- 异步任务模式，支持长时任务执行
|
||
- 可扩展多个子 agent（开发、测试、审查、运维等）
|
||
|
||
### 1.3 典型工作流
|
||
|
||
```
|
||
1. 用户向 CodeBuddy 描述需求（"给项目加个用户管理模块"）
|
||
2. CodeBuddy 拆解任务，制定方案
|
||
3. 用户确认方案
|
||
4. CodeBuddy 通过 MCP 调用子 Dev Agent 执行具体开发
|
||
5. CodeBuddy 轮询任务进度，阶段性反馈给用户
|
||
6. 子 agent 完成后，CodeBuddy 验收质量
|
||
7. 有问题 → CodeBuddy 提修改意见 → 子 agent 修改
|
||
8. 没问题 → 汇总结果给用户
|
||
```
|
||
|
||
---
|
||
|
||
## 二、架构总览
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ 用户 │
|
||
└──────┬───────┘
|
||
│ 自然语言交互
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ CodeBuddy（主控） │
|
||
│ • 理解需求 │
|
||
│ • 拆解任务 & 制定方案 │
|
||
│ • 调度子 agent │
|
||
│ • 质量验收 & 结果汇总 │
|
||
└───────────┬──────────────────┬──────────────────┘
|
||
│ MCP HTTP 调用 │ MCP HTTP 调用
|
||
▼ ▼
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│ Dev Agent │ │ Test Agent │ ...更多子 agent
|
||
│ (全栈代码开发) │ │ (测试编写执行) │
|
||
│ - ADK + LiteLlm │ │ - ADK + LiteLlm │
|
||
│ - MCP Server │ │ - MCP Server │
|
||
└────────┬─────────┘ └────────┬─────────┘
|
||
│ 内部工具 │ 内部工具
|
||
▼ ▼
|
||
┌─────────┐ ┌─────────┐
|
||
│ 文件系统 │ │ 终端 │
|
||
│ Git │ │ 构建命令 │
|
||
└─────────┘ └─────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、阶段规划
|
||
|
||
### 阶段一：加固代码辅助 Agent ✅
|
||
|
||
**目标：** 让 Dev Agent 具备完整的全栈代码开发能力（内部能力建设）
|
||
|
||
#### 1.1 接入文件系统工具 ✅
|
||
- 使用 `@modelcontextprotocol/server-filesystem`（Node.js MCP server）
|
||
- 能力：读取文件、写入文件、列出目录、搜索文件
|
||
- 配置：`StdioConnectionParams` + 30s 超时
|
||
|
||
#### 1.2 接入终端命令执行工具 ✅
|
||
- 实现方式：Python 原生 `FunctionTool` + `asyncio.create_subprocess_shell`
|
||
- 最初尝试 MCP server 但 Windows 下通信不稳定，改为直接函数工具
|
||
- 能力：执行 shell 命令（编译、构建、测试等），支持超时控制和输出截断
|
||
|
||
#### 1.3 优化 Agent 指令与角色 ✅
|
||
- 明确身份：全栈开发子 Agent，接受 CodeBuddy 调度
|
||
- 四大模块：工作流程 / 工作边界 / 编译构建守则 / 报告格式
|
||
- 上报机制：架构决策、依赖不兼容、环境问题、能力范围外
|
||
- 保护机制：连续修复 3 次仍失败则上报
|
||
|
||
**涉及文件：**
|
||
```
|
||
my_agent/
|
||
├── agent.py # Dev Agent 主文件
|
||
├── .env # 环境配置
|
||
└── __init__.py
|
||
mcp_tools/
|
||
└── command_executor/ # （备用，当前未使用）
|
||
└── server.py
|
||
```
|
||
|
||
---
|
||
|
||
### 阶段二：Dev Agent 暴露为 MCP Server（HTTP/SSE）
|
||
|
||
**目标：** 将 Dev Agent 包装为 MCP 服务器，CodeBuddy 可通过 HTTP 调用
|
||
|
||
#### 2.1 MCP Server（SSE 模式）
|
||
- 使用 `mcp` Python SDK 的 SSE server
|
||
- 通信协议：HTTP + Server-Sent Events
|
||
- 端口：可配置（默认 8001）
|
||
|
||
#### 2.2 异步任务接口
|
||
暴露以下 MCP 工具：
|
||
|
||
| 工具名 | 描述 | 参数 |
|
||
|--------|------|------|
|
||
| `submit_task` | 提交开发任务 | `description: str`, `project_path: str`, `requirements?: str` |
|
||
| `get_task_status` | 查询任务状态 | `task_id: str` |
|
||
| `get_task_result` | 获取任务结果 | `task_id: str` |
|
||
| `get_task_log` | 获取任务执行日志 | `task_id: str` |
|
||
| `cancel_task` | 取消任务 | `task_id: str` |
|
||
| `list_tasks` | 列出任务列表 | `status?: str` |
|
||
|
||
任务状态流转：`pending` → `running` → `completed` / `failed`
|
||
|
||
#### 2.3 任务管理器
|
||
- 内存中的任务队列（支持并发）
|
||
- 任务日志持久化（文件存储）
|
||
- 任务结果结构化返回
|
||
|
||
#### 2.4 CodeBuddy 接入验证
|
||
- CodeBuddy 配置 MCP 客户端连接 Dev Agent
|
||
- 验证：提交任务 → 轮询进度 → 获取结果 → 验收
|
||
|
||
**涉及文件：**
|
||
```
|
||
mcp_server/
|
||
├── __init__.py
|
||
├── server.py # MCP SSE server 主入口
|
||
├── task_manager.py # 异步任务管理器
|
||
├── agent_runner.py # 封装 ADK agent 调用
|
||
└── task_store.py # 任务持久化存储
|
||
```
|
||
|
||
---
|
||
|
||
### 阶段三：完善协作流程
|
||
|
||
**目标：** 优化 CodeBuddy 与子 agent 的协作效率
|
||
|
||
#### 3.1 任务描述规范
|
||
- 定义标准化的任务提交格式
|
||
- 包含：需求描述、项目路径、技术约束、验收标准
|
||
|
||
#### 3.2 增量修改支持
|
||
- 支持基于已有修改继续迭代（CodeBuddy 提修改意见 → agent 修改）
|
||
- 任务关联与版本管理
|
||
|
||
#### 3.3 错误处理与重试
|
||
- 子 agent 失败时的错误报告格式
|
||
- CodeBuddy 端的重试策略
|
||
|
||
---
|
||
|
||
### 阶段四：扩展更多子 Agent（远期）
|
||
|
||
| Agent | 职责 | 主要工具 |
|
||
|-------|------|----------|
|
||
| Dev Agent | 全栈代码开发 | 文件系统、终端、Git |
|
||
| Test Agent | 测试编写与执行 | 终端、覆盖率工具 |
|
||
| Review Agent | 代码审查 | 文件系统、静态分析 |
|
||
| DevOps Agent | 部署与运维 | 云平台、CI/CD |
|
||
|
||
---
|
||
|
||
## 四、技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 主控 | CodeBuddy（对话式调度） |
|
||
| 子 Agent 框架 | Google ADK (Python) |
|
||
| LLM 接入 | LiteLlm → vLLM 兼容端点 |
|
||
| MCP | `mcp` Python SDK（官方） |
|
||
| Agent 内部工具 | 文件系统 MCP Server + Python 原生 FunctionTool |
|
||
| 任务存储 | 本地 JSON 文件（初期） |
|
||
| 通信协议 | HTTP/SSE (MCP) |
|
||
|
||
---
|
||
|
||
## 五、实施路线
|
||
|
||
| 阶段 | 内容 | 状态 |
|
||
|------|------|------|
|
||
| 阶段一 | Dev Agent + 文件系统 + 终端工具 | ✅ 完成 |
|
||
| 阶段二 | MCP Server + 异步任务 | 🔄 进行中 |
|
||
| 阶段三 | 协作流程优化 | ⏳ 待开始 |
|
||
| 阶段四 | 扩展子 agent | ⏳ 待开始 |
|
||
|
||
---
|
||
|
||
## 六、项目结构
|
||
|
||
```
|
||
agent/
|
||
├── PLAN.md # 本文件
|
||
├── my_agent/ # Dev Agent
|
||
│ ├── agent.py # Agent 定义（含文件系统 MCP + run_command 工具）
|
||
│ ├── .env # 环境变量
|
||
│ └── __init__.py
|
||
├── mcp_server/ # MCP HTTP Server（阶段二）
|
||
│ ├── server.py # MCP SSE server 主入口
|
||
│ ├── task_manager.py # 异步任务管理器
|
||
│ ├── agent_runner.py # 封装 ADK agent 调用
|
||
│ ├── task_store.py # 任务持久化存储
|
||
│ └── __init__.py
|
||
├── mcp_tools/ # 自定义 MCP 工具（备用）
|
||
│ └── command_executor/
|
||
│ ├── server.py
|
||
│ └── __init__.py
|
||
└── .venv/ # Python 虚拟环境
|
||
```
|