nelson
7f3176efc7
- 将 agents/root_agent、agents/note_agent 移至项目根目录 - 将 base/ 重命名为 agent_base/，避免被ADK误识别为agent - 移除所有 __init__.py 中的 sys.path.insert hack - root_agent 添加 note_agent 作为子智能体（sub_agents） - 更新所有 import 路径 - 更新 README.md 和 API_DOC.md
169 lines
4.4 KiB
Markdown
169 lines
4.4 KiB
Markdown
# 慧遇 Agent
|
||
|
||
基于 Google ADK (Agent Development Kit) 构建的智能体项目，支持多智能体协作、多用户会话管理和 REST API 集成。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── root_agent/ # 根智能体（小慧）
|
||
│ ├── __init__.py
|
||
│ └── agent.py # 定义 root_agent，包含子智能体引用
|
||
├── note_agent/ # 笔记子智能体
|
||
│ ├── __init__.py
|
||
│ ├── agent.py # 定义 root_agent（ADK 要求导出名）
|
||
│ └── note_formatter.py # Markdown 笔记格式化器
|
||
├── agent_base/ # Agent 基类
|
||
│ ├── __init__.py
|
||
│ └── agent_base.py # HuiYuBaseAgent（防注入 + 日志）
|
||
├── common/ # 公共工具
|
||
│ ├── __init__.py # 环境初始化（.env 加载、日志配置）
|
||
│ ├── logger.py # 模型调用耗时日志
|
||
│ └── prompt_guard.py # 防提示词注入检测
|
||
├── .env # 环境变量配置（不提交到 Git）
|
||
├── .env.example # 配置示例
|
||
├── API_DOC.md # REST API 接口文档
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Python >= 3.10
|
||
- pip
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
主要依赖：
|
||
- `google-adk` — Google Agent Development Kit
|
||
- `python-dotenv` — 环境变量管理
|
||
- `litellm` — 多模型适配层（对接 MiniMax 等大模型）
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env`：
|
||
|
||
```env
|
||
MINIMAX_API_KEY=your_api_key_here
|
||
MINIMAX_API_BASE=https://api.minimaxi.com/v1
|
||
MINIMAX_MODEL=openai/MiniMax-M2.7
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
# Web UI 模式（带聊天界面）
|
||
adk web .
|
||
|
||
# API 服务模式（纯 REST API，适合外部集成）
|
||
adk api_server . --auto_create_session
|
||
```
|
||
|
||
启动后访问 `http://127.0.0.1:8000`。
|
||
|
||
## 智能体架构
|
||
|
||
```
|
||
root_agent（小慧）
|
||
├── 通用对话：回答用户问题
|
||
└── 子智能体委派：
|
||
└── note_agent（笔记助手）
|
||
├── generate_text_note — 生成文本笔记
|
||
└── generate_image_note — 生成图片笔记
|
||
```
|
||
|
||
当用户请求涉及笔记生成、内容整理时，root_agent 会自动委派给 note_agent 处理。
|
||
|
||
## API 集成
|
||
|
||
使用 `adk api_server` 启动后，可通过 REST API 与 Agent 对话：
|
||
|
||
```bash
|
||
# 启动 API 服务
|
||
adk api_server . --auto_create_session --port 8000
|
||
|
||
# 发送对话
|
||
curl -X POST http://localhost:8000/run \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"app_name": "root_agent",
|
||
"user_id": "user_001",
|
||
"session_id": "my_session",
|
||
"new_message": {"role": "user", "parts": [{"text": "你好"}]}
|
||
}'
|
||
```
|
||
|
||
详细的接口文档见 [API_DOC.md](API_DOC.md)，Swagger 文档地址：`http://localhost:8000/docs`
|
||
|
||
## 内置能力
|
||
|
||
所有继承 `HuiYuBaseAgent` 的 Agent 自动获得：
|
||
|
||
### 防提示词注入
|
||
|
||
模型调用前自动检测用户输入中的注入攻击（角色扮演、指令泄露、分隔符注入、越狱尝试等），检测到时拒绝请求。
|
||
|
||
### 模型调用日志
|
||
|
||
每次模型调用完成后自动记录 Agent 名称、模型版本、调用耗时、Token 用量：
|
||
|
||
```
|
||
2026-04-06 07:54:59 [adk.agent] INFO - 模型调用完成 | agent=huiyu_agent model=MiniMax-M2.7 latency=11.701s prompt_tokens=78 completion_tokens=31 total_tokens=109
|
||
```
|
||
|
||
## 新增 Agent
|
||
|
||
在项目根目录下创建新的子目录即可：
|
||
|
||
```
|
||
my_new_agent/
|
||
├── __init__.py # 留空即可
|
||
└── agent.py # 必须导出名为 root_agent 的变量
|
||
```
|
||
|
||
`agent.py` 示例：
|
||
|
||
```python
|
||
from agent_base.agent_base import HuiYuBaseAgent
|
||
from google.adk.models.lite_llm import LiteLlm
|
||
import os
|
||
|
||
model = LiteLlm(
|
||
model=os.getenv("MINIMAX_MODEL"),
|
||
api_base=os.getenv("MINIMAX_API_BASE"),
|
||
api_key=os.getenv("MINIMAX_API_KEY"),
|
||
)
|
||
|
||
root_agent = HuiYuBaseAgent(
|
||
name="my_agent",
|
||
model=model,
|
||
description="我的智能体",
|
||
instruction="你是一个专业的助手。",
|
||
)
|
||
```
|
||
|
||
> **注意**：ADK 要求每个 agent 目录的 `agent.py` 中必须导出名为 `root_agent` 的变量。
|
||
|
||
如需作为 root_agent 的子智能体，在 `root_agent/agent.py` 中添加引用：
|
||
|
||
```python
|
||
from my_new_agent.agent import root_agent as my_new_agent
|
||
|
||
root_agent = HuiYuBaseAgent(
|
||
name="huiyu_agent",
|
||
...,
|
||
sub_agents=[my_new_agent],
|
||
)
|
||
```
|
||
|
||
重启服务后新 Agent 自动生效。
|