ADK-agents/README.md

# Dev Agent — 全栈开发子 Agent

基于 Google ADK (Agent Development Kit) 构建的全栈开发子 Agent，通过 A2A / MCP / REST API 多种方式调用，支持文件操作、终端命令、会话持久化、上下文压缩、长期记忆。

## 架构总览

```
用户 / CodeBuddy（主控）
        │
        ├── MCP ──► mcp_dev_agent/server.py ──┐
        │                                       │
        └── REST ─► api_server.py ◄─────────────┘
                        │
                        ▼
                   App（dev_app）
                        │  events_compaction_config（LLM 摘要压缩）
                        ▼
              LlmAgent（dev_agent / 花花）
                        │
              ┌─────────┼─────────┐
              ▼         ▼         ▼
          文件系统   终端命令   记忆系统
            MCP    run_command  preload_memory
```

## 核心能力

| 能力 | 说明 |
|------|------|
| **文件系统操作** | 读/写/列目录/搜索等 14 个工具（MCP: server-filesystem） |
| **终端命令执行** | 异步 subprocess，支持编译/构建/测试 |
| **网络搜索** | Tavily 搜索 + Fetch 抓取（默认关闭，见下文说明） |
| **SQLite 会话持久化** | 重启不丢，多入口共享 |
| **上下文自动压缩** | 每 20 轮 LLM 摘要，长对话不爆 context window |
| **长期记忆框架** | InMemory + 自动存取，可扩展为 Chroma 向量库 |
| **REST API** | `/run`、`/run_sse`、会话管理、Swagger UI |
| **MCP 接口** | 可直接接入 CodeBuddy / Cursor / Windsurf |
| **A2A 协议** | Agent-to-Agent 标准协议（备用方案） |

## 快速开始

### 1. 环境准备

```bash
# 进入项目目录
cd d:/nzy/workspace_python/agent

# 安装依赖（已装可跳过）
pip install -r requirements.txt

# 配置环境变量
# 编辑 my_agent/.env，填入你的 vLLM API Key 等
```

### 2. 启动 API Server

这是最主要的服务入口，提供 REST API + Swagger UI。

```bash
python api_server.py
```

启动后访问：
- **Swagger UI**: http://127.0.0.1:8001/docs — 浏览器直接测试接口
- **健康检查**: http://127.0.0.1:8001/health
- **列出 Agent**: http://127.0.0.1:8001/list-apps

### 3. 配置 MCP（CodeBuddy 调用）

在 CodeBuddy 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "dev-agent": {
      "command": "python",
      "args": ["d:/nzy/workspace_python/agent/mcp_dev_agent/server.py"],
      "env": {
        "DEV_AGENT_API_URL": "http://127.0.0.1:8001",
        "DEV_AGENT_APP_NAME": "dev_agent",
        "DEV_AGENT_USER_ID": "codebuddy"
      }
    }
  }
}
```

重启 CodeBuddy 后，即可通过 `run_dev_agent` 工具调用 Dev Agent。

## 使用方式

### 方式一：Swagger UI（最直观）

打开 http://127.0.0.1:8001/docs ，在浏览器里直接测试。

**常用接口**：

- `POST /run` — 同步运行 agent，返回完整事件列表
- `POST /run_sse` — SSE 流式运行
- `GET /apps/{app}/users/{user}/sessions/{id}` — 获取会话
- `POST /apps/{app}/users/{user}/sessions/{id}` — 创建会话

### 方式二：命令行对话

```bash
# 新会话
python chat.py

# 指定 session_id 继续对话
python chat.py --session my_session

# 列出所有会话
python chat.py --list

# 删除会话
python chat.py --delete my_session
```

### 方式三：MCP 工具（CodeBuddy / Cursor）

配置好 MCP 后，直接让 IDE 中的 AI 调用 `run_dev_agent` 工具。

**工具参数**：

| 参数 | 必填 | 说明 |
|------|------|------|
| `task` | ✅ | 任务描述，越详细越好 |
| `session_id` | ❌ | 会话 ID，不传则为 `default`。用于多轮续聊 |

### 方式四：curl 直接调用

```bash
curl -X POST http://127.0.0.1:8001/run \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "dev_agent",
    "userId": "test_user",
    "sessionId": "test_001",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "你好，请介绍一下你自己"}]
    }
  }'
```

## 项目结构

```
agent/
├── api_server.py              # REST API Server（主入口）
├── chat.py                    # CLI 对话工具
├── a2a_server.py              # A2A Server（备用，已被 API Server 取代）
├── a2a_client.py              # A2A 客户端测试（调试用）
├── test_sse_client.py         # SSE 测试（调试用）
│
├── my_agent/
│   ├── __init__.py
│   ├── agent.py               # Agent 定义（人设、工具、instruction）
│   ├── app.py                 # App 容器（上下文压缩配置）
│   └── .env                   # 环境变量配置
│
├── mcp_dev_agent/             # Dev Agent MCP Server（CodeBuddy 入口）
│   ├── server.py
│   └── README.md
│
├── mcp_server/                # 旧版 MCP Server（已废弃，保留参考）
│   └── ...
│
├── mcp_tools/                 # 备用 MCP 工具（已废弃，保留参考）
│   └── command_executor/
│
├── data/                      # 数据目录（运行时生成）
│   └── sessions.db            # SQLite 会话数据库
│
└── PLAN.md                    # 项目计划文档
```

## 配置说明

### 环境变量（my_agent/.env）

```env
# vLLM API 配置
VLLM_API_BASE=https://9router.aqroid.cn/v1    # vLLM 端点地址
VLLM_MODEL=aq-first-combo                      # 模型名
VLLM_API_KEY=sk-...                            # API Key

# Agent 工作目录（文件系统 MCP 根目录）
AGENT_WORKSPACE_DIR=D:\nzy\workspace_git

# Tavily 搜索 API Key（启用搜索工具时需要）
TAVILY_API_KEY=tvly-dev-...

# Windows 编码
PYTHONUTF8=1
```

### API Server 配置

通过环境变量或直接修改 `agents/my_agent/api_server.py`：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `API_SERVER_HOST` | `0.0.0.0` | 监听地址 |
| `API_SERVER_PORT` | `8001` | 监听端口 |

### MCP Server 配置

通过环境变量配置：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DEV_AGENT_API_URL` | `http://127.0.0.1:8001` | API Server 地址 |
| `DEV_AGENT_APP_NAME` | `dev_agent` | Agent 名称 |
| `DEV_AGENT_USER_ID` | `codebuddy` | 用户 ID（会话隔离用） |

## 会话与记忆

### 会话持久化

所有会话存储在 `data/sessions.db`（SQLite），重启服务不丢失。

- **同入口续聊**：同一个 session_id 下次接着聊
- **跨入口共享**：API Server、CLI、MCP 都用同一个数据库

### 上下文压缩

长对话会自动摘要压缩（默认每 20 轮），防止 context window 溢出：

- 滑动窗口压缩 + 重叠摘要（保持连续性）
- Token 超阈值紧急压缩（默认 50k）
- 原始事件完整保留（可回溯）

配置在 `agents/my_agent/app.py` 的 `EventsCompactionConfig`。

### 长期记忆

当前使用 `InMemoryMemoryService`（内存版），特性：

- 每轮对话结束自动保存（`after_agent_callback`）
- 每轮对话开始自动加载相关记忆（`preload_memory`）
- 进程重启后记忆丢失

**后续可扩展**：替换为 `ChromaMemoryService` 等向量数据库，实现持久化语义搜索。

## 工具说明

### 文件系统工具（14 个）

read_file、read_text_file、read_media_file、read_multiple_files、write_file、edit_file、create_directory、list_directory、list_directory_with_sizes、directory_tree、move_file、search_files、get_file_info、list_allowed_directories

### 终端命令

- **run_command** — 执行终端命令，支持自定义工作目录和超时

### 记忆工具

- **preload_memory** — 每轮自动检索并注入相关历史记忆（系统自动调用，不占工具回合）

### 网络搜索工具（默认关闭）

Tavily 搜索 + Fetch 抓取默认注释掉了，因为 vLLM 端点有 413（请求体过大）限制。如需启用：

1. 取消 `agents/my_agent/agent.py` 中 `fetch_mcp` 和 `tavily_mcp` 的注释
2. 配置 `TAVILY_API_KEY` 环境变量

## 工作流程

标准工作流程：

1. 理解任务需求和项目上下文
2. 使用文件系统工具浏览项目结构、读取相关文件
3. 编写或修改代码
4. 使用 run_command 运行编译/构建/测试
5. 验证结果后，结构化报告完成情况

**报告格式**：
- 状态：成功 / 部分完成 / 失败（需上报）
- 修改的文件：列出所有修改的文件路径
- 变更摘要：简述做了什么
- 验证结果：编译/测试是否通过
- 需要主控关注：如有问题，详细说明

## 部署说明

### 本地开发

```bash
# 终端 1：启动 API Server
python api_server.py

# 终端 2（可选）：用 CLI 测试
python chat.py

# 或者直接用 Swagger UI：http://127.0.0.1:8001/docs
```

### 上云准备

- API Server 是标准 FastAPI 应用，可直接部署到任何支持 Python 的平台
- SQLite 会话数据库需换成数据库服务（PostgreSQL / MySQL）
- MemoryService 需换成托管向量数据库（Chroma / Pinecone / Vertex AI）
- 文件系统 MCP 需接入云存储或挂载盘

## 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| Agent 框架 | Google ADK | 2.5.0 |
| LLM 接入 | LiteLLM + vLLM (OpenAI 兼容) | 1.80.0 |
| MCP | Model Context Protocol SDK | 1.29.0 |
| HTTP 服务 | FastAPI + Uvicorn | - |
| 会话存储 | SQLite | - |
| A2A 协议 | a2a-sdk | 1.1.2 |

## 常见问题

### Q: 启动后 MCP 工具连不上？

A: 第一次启动 npx 需要下载 MCP 包，可能需要 30 秒到 1 分钟。如果超时，检查网络连接。

### Q: 调用时报 413 Request Entity Too Large？

A: vLLM 端点的 nginx 限制了请求体大小。当前已暂时关闭 Tavily 和 Fetch 工具以减小请求体。如需要启用，需联系端点管理员调大限制。

### Q: 会话数据存在哪？

A: `data/sessions.db`，SQLite 格式，可用任何 SQLite 工具打开查看。

### Q: 怎么重置会话？

A: 用 CLI 的 `python chat.py --delete <session_id>`，或直接调用 DELETE 会话 API，或直接删除 `data/sessions.db` 文件。

## 许可证

MIT