146 lines
3.2 KiB
Markdown
146 lines
3.2 KiB
Markdown
# 慧遇 Agent
|
||
|
||
慧遇智能体项目，基于 Google ADK (Agent Development Kit) 构建。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
workspace/
|
||
├── agents/ # 所有 Agent 模块
|
||
│ ├── __init__.py
|
||
│ └── root_agent/ # Root Agent
|
||
│ ├── __init__.py
|
||
│ └── agent.py
|
||
├── base/ # 基础工具类
|
||
│ ├── __init__.py
|
||
│ └── agent.py # HuiYuBaseAgent 基类
|
||
├── common/ # 公共模块
|
||
│ ├── __init__.py # 环境初始化（.env 加载、日志配置）
|
||
│ ├── logger.py # 模型调用耗时日志
|
||
│ └── prompt_guard.py # 防提示词注入检测
|
||
├── .env # 环境变量配置（不提交到 Git）
|
||
├── .env.example # 配置示例（可提交到 Git）
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Python >= 3.10
|
||
- pip
|
||
|
||
## 环境搭建
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install "google-adk[extensions]" python-dotenv
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制示例配置文件并填入你的 API Key：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件：
|
||
|
||
```env
|
||
# MiniMax API Key（替换为你自己的）
|
||
MINIMAX_API_KEY=your_api_key_here
|
||
|
||
# MiniMax API 地址
|
||
MINIMAX_API_BASE=https://api.minimaxi.com/v1
|
||
|
||
# 模型名称
|
||
MINIMAX_MODEL=openai/MiniMax-M2.7
|
||
```
|
||
|
||
### 3. 启动服务
|
||
|
||
```bash
|
||
cd agents
|
||
adk web
|
||
```
|
||
|
||
启动后访问 http://127.0.0.1:8000，在下拉菜单中选择 Agent 即可开始对话。
|
||
|
||
## 内置能力
|
||
|
||
所有继承 `HuiYuBaseAgent` 的 Agent 自动获得以下能力：
|
||
|
||
### 防提示词注入
|
||
|
||
在模型调用前自动检测用户输入中的提示词注入攻击，包括：
|
||
- 角色扮演 / 身份覆盖
|
||
- 指令泄露尝试
|
||
- 分隔符注入
|
||
- 越狱尝试
|
||
|
||
检测到注入时会拒绝请求并返回提示。
|
||
|
||
### 模型调用日志
|
||
|
||
每次模型调用完成后自动记录：
|
||
- Agent 名称
|
||
- 模型版本
|
||
- 调用耗时
|
||
- Token 使用量（prompt / completion / total）
|
||
|
||
日志示例：
|
||
|
||
```
|
||
2026-04-06 07:54:59 [adk.agent] INFO - 模型调用完成 | agent=minimax_agent model=MiniMax-M2.7 latency=11.701s prompt_tokens=78 completion_tokens=31 total_tokens=109
|
||
```
|
||
|
||
## 新增 Agent
|
||
|
||
在 `agents/` 目录下创建新的子目录即可：
|
||
|
||
```
|
||
agents/
|
||
├── root_agent/
|
||
│ ├── __init__.py
|
||
│ └── agent.py
|
||
└── my_new_agent/ # 新增 Agent
|
||
├── __init__.py # 内容同 root_agent/__init__.py
|
||
└── agent.py
|
||
```
|
||
|
||
`__init__.py` 内容（用于设置 Python 路径）：
|
||
|
||
```python
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
sys.path.insert(0, str(Path(__file__).parent.parent.parent))
|
||
|
||
from . import agent
|
||
|
||
__all__ = ["agent"]
|
||
```
|
||
|
||
`agent.py` 中继承 `HuiYuBaseAgent`：
|
||
|
||
```python
|
||
from base.agent 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"),
|
||
)
|
||
|
||
my_agent = HuiYuBaseAgent(
|
||
name="my_agent",
|
||
model=model,
|
||
instruction="你是一个专业的助手。",
|
||
)
|
||
```
|
||
|
||
重启 `adk web` 后，新 Agent 会自动出现在下拉菜单中。
|