# 慧遇 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 会自动出现在下拉菜单中。