Agents/README.md

慧遇 Agent

基于 Google ADK (Agent Development Kit) 构建的智能体项目，支持多智能体协作、多用户会话管理和 REST API 集成。

项目结构

├── root_agent/             # 根智能体（小慧）
│   ├── __init__.py
│   └── agent.py            # 定义 root_agent，包含子智能体引用
├── critical_awareness_agent/  # 临界觉察助手
│   ├── __init__.py
│   └── agent.py            # 三界觉察引导
├── lumina_agent/           # 卢慧老师智能体
│   ├── __init__.py
│   └── agent.py            # 会式心理学讲师
├── l1_live_course_agent/   # L1 入门课助教
│   ├── __init__.py
│   └── agent.py
├── l2_training_camp_agent/ # L2 训练营助教
│   ├── __init__.py
│   └── agent.py
├── l3_wisdom_camp_agent/   # L3 大本营助教
│   ├── __init__.py
│   └── agent.py
├── l4_mystery_gate_agent/  # L4 众妙之门助教
│   ├── __init__.py
│   └── agent.py
├── l5_refinement_agent/    # L5 精修班助教
│   ├── __init__.py
│   └── agent.py
├── image_agent/            # 图片查询助手
│   ├── __init__.py
│   ├── agent.py            # 定义 root_agent
│   └── image_tools.py      # 图片搜索工具
├── agent_base/             # Agent 基类
│   ├── __init__.py
│   └── agent_base.py       # HuiYuBaseAgent（防注入 + 日志）
├── common/                 # 公共工具
│   ├── __init__.py         # 环境初始化（.env 加载、日志配置）
│   ├── logger.py           # 模型调用耗时日志
│   ├── models.py           # 模型工厂（MiniMax/DeepSeek）
│   ├── profile_loader.py   # Profile 文件加载器
│   └── prompt_guard.py     # 防提示词注入检测
├── profiles/               # 助教老师 Profile 文件
│   ├── l1_live_course.md
│   ├── l2_training_camp.md
│   ├── l3_wisdom_camp.md
│   ├── l4_mystery_gate.md
│   └── l5_refinement.md
├── .env                    # 环境变量配置（不提交到 Git）
├── .env.example            # 配置示例
├── API_DOC.md              # REST API 接口文档
├── requirements.txt
└── README.md

环境要求

• Python >= 3.10
• pip

快速开始

1. 安装依赖

pip install -r requirements.txt

主要依赖：

• google-adk — Google Agent Development Kit
• python-dotenv — 环境变量管理
• litellm — 多模型适配层（对接 MiniMax/DeepSeek 等大模型）
• httpx — HTTP 客户端（图片查询工具使用）

2. 配置环境变量

cp .env.example .env

编辑 .env：

# MiniMax 配置
MINIMAX_API_KEY=your_api_key_here
MINIMAX_API_BASE=https://api.minimaxi.com/v1
MINIMAX_MODEL=openai/MiniMax-M2.7

# DeepSeek 配置（可选）
DEEPSEEK_API_KEY=your_api_key_here
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
DEEPSEEK_MODEL=openai/deepseek-chat

# 图片服务配置（可选，用于 image_agent）
IMAGE_API_BASE=http://localhost:8765

3. 启动服务

# Web UI 模式（带聊天界面）
adk web .

# API 服务模式（纯 REST API，适合外部集成）
adk api_server . --auto_create_session

启动后访问 http://127.0.0.1:8000。

智能体架构

root_agent（小慧）
├── 通用对话：回答用户问题
└── 子智能体委派：
    └── critical_awareness_agent（临界觉察助手）

独立 Agent（手动选择）：
├── lumina_agent — 会式心理学讲师（卢慧老师）
├── l1_live_course_agent — 入门课助教
├── l2_training_camp_agent — 训练营助教
├── l3_wisdom_camp_agent — 大本营助教
├── l4_mystery_gate_agent — 众妙之门助教
├── l5_refinement_agent — 精修班助教
└── image_agent — 图片查询助手

当用户出现心智散乱、情绪化或认知混淆时，root_agent 会委派给 critical_awareness_agent 处理。

API 集成

使用 adk api_server 启动后，可通过 REST API 与 Agent 对话：

# 启动 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，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

模型工厂

通过 common/models.py 集中管理模型实例：

from common.models import minimax_model, deepseek_model

# 直接使用，无需重复创建
root_agent = HuiYuBaseAgent(
    name="my_agent",
    model=minimax_model,  # 或 deepseek_model
    ...
)

新增 Agent

在项目根目录下创建新的子目录即可：

my_new_agent/
├── __init__.py         # 留空即可
└── agent.py            # 必须导出名为 root_agent 的变量

agent.py 示例：

from agent_base.agent_base import HuiYuBaseAgent
from common.models import minimax_model

root_agent = HuiYuBaseAgent(
    name="my_agent",
    model=minimax_model,
    description="我的智能体",
    instruction="你是一个专业的助手。",
)

注意：ADK 要求每个 agent 目录的 agent.py 中必须导出名为 root_agent 的变量。

如需作为 root_agent 的子智能体，在 root_agent/agent.py 中添加引用：

from my_new_agent.agent import root_agent as my_new_agent

root_agent = HuiYuBaseAgent(
    name="huiyu_agent",
    ...,
    sub_agents=[my_new_agent],
)

重启服务后新 Agent 自动生效。

图片查询 Agent

image_agent 提供图片库查询能力，支持：

• AI 语义搜索：根据自然语言描述搜索图片
• 查看详情：获取图片完整 OCR 内容和元数据
• 浏览列表：分页查看图片库

需要配置 IMAGE_API_BASE 指向图片服务地址。

助教 Agent 体系

L1-L5 五个层级的助教 Agent 通过 profiles/ 目录下的 Markdown 文件加载配置：

• 每个助教独立运行，用户可在 Web UI 下拉菜单手动选择
• Profile 文件更新后重启服务即可生效
• 助教对外自称"XX助教老师"，不使用 L1-L5 编号

开发规范

1. 模型使用：统一从 common.models 导入，不要重复创建
2. Profile 加载：使用 common.profile_loader.load_profile() 从文件加载
3. 工具封装：复杂逻辑封装为 Tool，通过 tools 参数传入 Agent
4. 环境变量：敏感配置放入 .env，代码中通过 os.getenv() 读取