handsomeAq 6f3f9c7df1 agent1.1版本修改了mcp逻辑多agent测试通过

2026-07-31 17:35:07 +08:00

10 KiB

Raw Blame History

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. 环境准备

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

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

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

2. 启动 API Server

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

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 配置中添加：

{
  "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} — 创建会话

方式二：命令行对话

# 新会话
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 直接调用

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）

# 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（请求体过大）限制。如需启用：

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

工作流程

标准工作流程：

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

报告格式：

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

部署说明

本地开发

# 终端 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

10 KiB Raw Blame History Unescape Escape