Agents/README.md

慧遇 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. 克隆项目

git clone <your-repo-url>
cd <project-directory>

2. 安装依赖

pip install -r requirements.txt

主要依赖：

• google-adk — Google Agent Development Kit
• python-dotenv — 环境变量管理
• litellm — 多模型适配层

3. 配置环境变量

复制示例配置文件并填入你的 API Key：

cp .env.example .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

4. 启动服务

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 路径）：

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent.parent))

from . import agent

__all__ = ["agent"]

agent.py 中继承 HuiYuBaseAgent：

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