# PyAgent

**Repository Path**: sealphp/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-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Server

基于 FastAPI + DeepSeek 的企业级 AI Agent 服务。

## 特性

- **ReAct Agent 引擎** — 思考 → 工具调用 → 观察 → 回答的自动循环
- **工具注册中心** — 继承 `BaseTool` 即可扩展，自动适配 function calling
- **LLM 抽象层** — 不绑定供应商，可切换任意 OpenAI 兼容模型
- **会话记忆** — 可插拔的记忆后端（内存 / Redis / 数据库）
- **企业就绪** — 配置管理、依赖注入、请求日志、API 版本化

## 快速开始

### 环境要求

- Python >= 3.11
- DeepSeek API Key（[申请地址](https://platform.deepseek.com/)）

### 安装

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

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

# 安装依赖
pip install -r requirements.txt
```

### 配置

项目会从根目录的 `.env` 读取配置。当前仓库没有提供 `.env.example`，可直接创建 `.env` 文件并填写最少配置：

```env
DEEPSEEK_API_KEY=sk-your-key-here
```

常用可选配置：

```env
APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8000
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
```

### 启动

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

```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
```

### 对话

```bash
curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -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" \
  -d '{"session_id": "上一次返回的session_id", "message": "继续刚才的话题"}'
```

## 项目结构

```
app/
├── main.py                 # 入口 + 生命周期管理
├── config.py               # 配置（pydantic-settings）
├── dependencies.py          # 依赖注入
├── api/
│   ├── router.py           # 路由聚合
│   └── v1/                 # API v1
│       ├── health.py
│       └── chat.py
├── core/
│   ├── llm/                # LLM 客户端
│   │   ├── base.py         # 抽象基类
│   │   └── deepseek.py     # DeepSeek 实现
│   ├── agent/              # Agent 引擎
│   │   └── base.py         # ReAct 执行器
│   ├── memory/             # 会话记忆
│   │   ├── base.py         # 抽象基类
│   │   └── in_memory.py    # 内存实现
│   └── tools/              # 工具系统
│       ├── base.py         # 工具基类
│       └── registry.py     # 注册中心
├── models/
│   └── schemas.py          # 数据模型
└── middleware/
    └── logging.py          # 请求日志
```

## 扩展工具

创建一个工具只需三步：

```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
```

## 路线图

详见 [ROADMAP.md](./ROADMAP.md)，共 7 个递进阶段：

1. ~~基础骨架~~ ✅
2. 工具能力
3. 记忆与上下文管理
4. 多 Agent 协作
5. 流式响应与实时交互
6. 企业级基础设施
7. 高级能力与生态

## License

MIT