init agent project

README.md

@@ -1,3 +1,145 @@
-# Agents
+# 慧遇 Agent
 
-慧遇所有的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 会自动出现在下拉菜单中。