# PyAgent

**Repository Path**: Gyfff325/py-agent

## Basic Information

- **Project Name**: PyAgent
- **Description**: 这是一个Agent项目，主题框架使用python语言
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-31
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Server

基于 FastAPI 的 AI Agent 服务，对接任意 OpenAI 兼容大模型（默认 DeepSeek），当前处于安全与可靠性持续完善阶段。

## 特性

- **ReAct Agent 引擎** — 思考 → 工具调用 → 观察 → 回答的自动循环
- **9 个内置工具** — 联网搜索、图片搜索、HTTP 请求、文件读写、数据库查询、代码执行、天气、时间；执行类默认关闭
- **工具注册中心** — 继承 `BaseTool` 即可扩展，自动适配 function calling
- **超时 & 熔断** — 工具执行自动超时、统一截断、冷却与半开恢复
- **LLM 抽象层** — 不绑定供应商，可切换任意 OpenAI 兼容模型
- **账号系统** — 用户名密码注册登录，PBKDF2 加盐哈希，HMAC 签名令牌
- **会话历史持久化** — SQLite 持久化，Redis 可选上下文缓存与分布式会话锁
- **自定义智能体** — 手写提示词或让 AI 联网搜资料后起草，会话可绑定人格
- **头像搜索与裁剪** — 联网搜图或传本地图，服务端裁剪成 128×128（绕开 CORS 限制）
- **语音朗读**（可选）— 回复自动出声，可切阿里云百炼或本地 GPT-SoVITS，音色按智能体配置
- **流式对话** — 推理、正文和工具调用通过 SSE 实时显示，支持中途停止并保留已生成内容
- **语音输入** — Chrome/Edge 等浏览器可直接语音转文字，后端 ASR provider 扩展点已预留
- **基础工程化** — 配置管理、依赖注入、请求日志、API 版本化

## 文档

详细文档从 [`docs/README.md`](docs/README.md) 开始：

- [系统架构](docs/architecture/ARCHITECTURE.md)
- [配置参考](docs/reference/CONFIGURATION.md)
- [API 参考](docs/reference/API.md)
- [账号与会话历史](docs/features/AUTH_AND_HISTORY.md)
- [自定义智能体](docs/features/CUSTOM_AGENTS.md)
- [语音合成](docs/features/TTS.md)
- [工具与安全边界](docs/reference/TOOLS.md)
- [开发与测试](docs/development/DEVELOPMENT.md)
- [安全与可靠性阶段任务](docs/plans/PHASE_SECURITY_RELIABILITY.md)

当前令牌吊销、登录限流、文件接口鉴权与用户级目录隔离、数据库迁移、事件级断点续传、后端 ASR provider 和网络层 DNS 重绑定防护仍未完成。生产启动会拒绝默认认证密钥，但仍需按配置参考完成 Nginx、Redis、数据库只读账号和出站网络策略。

## 快速开始

### 环境要求

- Python >= 3.11
- 一个 OpenAI 兼容大模型的 API Key（如 DeepSeek，[申请地址](https://platform.deepseek.com/)；也可用 OpenAI / Qwen / 本地模型等）

### 安装

```bash
# 克隆项目
git clone <repo-url> && cd agent

# 创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

# 安装项目依赖
pip install -e .
```

### 配置

复制 `.env.example` 为 `.env` 并填写必要配置：

```bash
cp .env.example .env
```

必填：

```env
# OpenAI 兼容接口，键名不绑定厂商（DeepSeek / OpenAI / Qwen / 本地模型均可）
LLM_API_KEY=sk-your-key-here
```

可选（按需启用工具）：

```env
# 联网搜索（启用 web_search 工具）
TAVILY_API_KEY=tvly-your-key-here

# 代码执行沙箱（启用 code_interpreter 工具）
E2B_API_KEY=e2b-your-key-here
TOOL_EXECUTION_ENABLED=true
```

其他可选配置：

```env
APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8000
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-pro
```

### 启动

项目根目录新增了一个统一启动脚本，直接运行即可：

```bash
python start.py
```

默认会读取 `.env` 中的 `APP_HOST`、`APP_PORT` 和 `APP_ENV`。

也可以临时覆盖：

```bash
python start.py --host 127.0.0.1 --port 9000
python start.py --reload
python start.py --no-reload
```

服务默认运行在 `http://127.0.0.1:8000`，开发环境自动启用 Swagger 文档：`http://127.0.0.1:8000/docs`

如果你仍然希望使用原始入口，也可以运行：

```bash
python -m app.main
```

## API

### 健康检查

```
GET /api/v1/health
```

### 对话

聊天接口需要登录令牌，先注册（或登录）拿到 token：

```bash
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"pw123456"}' | jq -r .token)

curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "你好，请介绍一下你自己"}'
```

响应：

```json
{
  "session_id": "019...",
  "message": "你好！我是一个企业级智能助手...",
  "steps": [],
  "usage": {}
}
```

带会话上下文的多轮对话：

```bash
curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"session_id": "上一次返回的session_id", "message": "继续刚才的话题"}'
```

查看历史会话列表：

```bash
curl http://127.0.0.1:8000/api/v1/conversations \
  -H "Authorization: Bearer $TOKEN"
```

## 项目结构

```
app/
├── main.py                 # 入口 + 生命周期管理
├── config.py               # 配置（pydantic-settings）
├── dependencies.py          # 依赖注入
├── api/
│   ├── router.py           # 路由聚合
│   └── v1/                 # API v1
│       ├── health.py
│       ├── auth.py         # 注册 / 登录 / 当前用户
│       ├── agents.py       # 自定义智能体 CRUD / AI 生成提示词
│       ├── conversations.py # 会话列表 / 消息 / 重命名 / 删除
│       ├── chat.py
│       └── files.py        # 上传 / 下载
├── repositories/           # 数据访问层（含会话归属校验）
├── core/
│   ├── auth.py             # 密码哈希、令牌、认证依赖
│   ├── avatar.py           # 头像拉取/裁剪（含 SSRF、解压炸弹防护）
│   ├── db.py               # 异步引擎、会话工厂、建表
│   ├── tts/                # 语音合成（抽象 + 阿里云 + GPT-SoVITS）
│   ├── llm/                # LLM 客户端
│   │   ├── base.py         # 抽象基类
│   │   └── openai_compatible.py  # OpenAI 兼容实现（DeepSeek / OpenAI / Qwen 等）
│   ├── agent/              # Agent 引擎
│   │   ├── base.py         # ReAct 执行器
│   │   └── prompt_builder.py # AI 起草系统提示词（先搜索再生成）
│   ├── memory/             # 会话记忆
│   │   ├── base.py         # 抽象基类
│   │   ├── sql_memory.py   # SQLite 持久化实现（当前使用）
│   │   └── in_memory.py    # 内存实现
│   └── tools/              # 工具系统
│       ├── base.py         # 工具基类（含超时/幂等/截断）
│       ├── registry.py     # 注册中心（含熔断器）
│       ├── utils.py        # 工具函数
│       └── builtin/        # 内置工具
│           ├── web_search.py       # Tavily 联网搜索
│           ├── image_search.py     # 图片搜索（Markdown 直接渲染）
│           ├── http_request.py     # HTTP 请求（含安全校验）
│           ├── file_reader.py      # 文件读取（PDF/Excel/CSV）
│           ├── file_writer.py      # 文件写入（限定根目录）
│           ├── database_query.py   # 只读 SQL 查询
│           ├── code_interpreter.py # E2B 沙箱代码执行
│           ├── weather.py          # Open-Meteo 天气查询
│           └── datetime_now.py     # 当前日期时间
├── models/
│   ├── schemas.py          # API 数据模型
│   └── db_models.py        # ORM 模型（用户 / 智能体 / 会话 / 消息）
└── middleware/
    └── logging.py          # 请求日志
```

## 内置工具

| 工具 | 说明 | API Key |
|------|------|---------|
| `web_search` | Tavily 联网搜索，获取实时信息 | `TAVILY_API_KEY` |
| `image_search` | 搜索图片并直接在对话中展示 | `TAVILY_API_KEY` |
| `http_request` | HTTP 请求外部 API（拦截内网地址） | 无需 |
| `file_reader` | 读取 PDF、Excel、CSV、文本文件 | 无需 |
| `file_writer` | 写入文件到限定根目录，前端可下载 | 无需 |
| `database_query` | 只读 SQL 查询（拦截写操作） | 无需 |
| `code_interpreter` | E2B 沙箱执行 Python 代码 | `E2B_API_KEY` |
| `weather` | Open-Meteo 城市或 IP 定位，支持当前天气与 1 至 7 天预报 | 无需 |
| `datetime_now` | 获取当前日期时间（支持时区） | 无需 |

执行类工具默认不向模型暴露，需设置 `TOOL_EXECUTION_ENABLED=true`。未配置 API Key 的已启用工具会返回明确提示。

`database_query` 连接的是 `DATABASE_URL` 指向的业务库，对模型完全可见。账号和会话历史存放在独立的 `APP_DATABASE_URL`，任何工具都无法访问。

## 扩展工具

创建一个工具只需三步：

```python
from app.core.tools.base import BaseTool

class MyTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_tool"

    @property
    def description(self) -> str:
        return "这个工具做什么"

    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "查询内容"}
            },
            "required": ["query"]
        }

    async def execute(self, query: str) -> str:
        return f"结果: {query}"
```

在 `app/dependencies.py` 中注册：

```python
from app.core.tools.my_tool import MyTool
_tool_registry.register(MyTool())
```

## 测试

```bash
pip install -e ".[dev]"
pytest
```

## 路线图

当前路线以[安全与可靠性阶段任务](docs/plans/PHASE_SECURITY_RELIABILITY.md)为准。

## License

MIT