# agent

**Repository Path**: qchen007/agent

## Basic Information

- **Project Name**: agent
- **Description**: agent
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Service

基于 Python 3.14+ 的智能 Agent 服务，使用 FastAPI 提供 HTTP 接口，LangGraph/LangChain 构建 Agent 工作流。

## 核心特性

- **多模式 Agent**：支持单 Agent 工具调用、技能驱动 Agent、多 Agent 协作三种模式
- **技能系统**：从磁盘 `skills/` 目录动态加载 Markdown 技能文件，自动匹配用户意图
- **多 Agent 协作**：支持 SubAgent 自动调度和 Supervisor 状态机路由
- **双模式响应**：支持直接返回和流式输出（SSE）
- **会话管理**：Agent 支持多会话并发，通过 session_id 隔离
- **共享工具库**：`src/tools/` 提供搜索、计算、时间、文件、URL 等常用工具

## 快速开始

```bash
# 安装依赖
uv sync

# 启动开发服务器（自动重载）
uv run uvicorn main:app --reload --port 8000
```

## 环境配置

复制 `.env.example` 为 `.env` 并配置：

```env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
TAVILY_API_KEY=tvly-xxx  # 可选，搜索功能需要
```

## Agent 模式

### 1. 单 Agent（工具调用）

使用 LangGraph + 内置工具，适合通用对话任务。

```bash
curl -X POST http://localhost:8000/api/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "session_id": "user123"}'
```

### 2. 技能驱动 Agent

基于 `deepagents`，从 `skills/` 目录加载 Markdown 技能文件，Agent 自动匹配合适的技能。

```bash
curl -X POST http://localhost:8000/api/skillagent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "帮我写一段 Python 代码"}'
```

### 3. 多 Agent 协作

**SubAgent 模式**：自动调度预定义的子代理（researcher/coder/writer）。

```bash
curl -X POST http://localhost:8000/api/multiagent/subagent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "计算 2+2"}'
```

**Supervisor 模式**：LLM 驱动的状态机，根据对话内容路由到不同专家 Agent。

```bash
curl -X POST http://localhost:8000/api/multiagent/supervisor/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "搜索并总结 Python 异步编程"}'
```

## 内置工具

| 工具 | 功能 |
|------|------|
| `search_web` | 网页搜索（需 TAVILY_API_KEY） |
| `calculator` | 数学计算（+, -, *, /, //, %, **, abs, max, min, round, sum, pow） |
| `get_current_time` | 获取当前时间 |
| `fetch_url` | 抓取网页内容 |
| `read_file` / `write_file` | 文件读写 |
| `count_words` | 统计字数 |
| `random_number` | 生成随机数 |

## 流式输出

所有 `/chat` 端点支持 `/chat/stream` 流式输出，使用 SSE 协议。

```bash
curl -X POST http://localhost:8000/api/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "你好"}'
```

SSE 事件类型：`start` / `chunk` / `tool_call` / `tool_result` / `done`

## 直接 LLM 调用

无 Agent、无工具，适合简单请求。

```bash
curl -X POST http://localhost:8000/api/llm/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好"}'
```

## 用户管理

```bash
# 创建用户
curl -X POST http://localhost:8000/api/users/ \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "email": "zhang@example.com"}'

# 列出用户
curl http://localhost:8000/api/users/list
```

## 健康检查

```bash
curl http://localhost:8000/liveness
curl http://localhost:8000/readiness
```

## 项目结构

```
src/
├── routes.py              # 聚合所有路由
├── config/                # pydantic-settings 配置管理
├── common/                # 共享工具
│   ├── agent_utils.py     # Agent 公共逻辑（create_chat_model 等）
│   └── middleware.py      # 中间件
├── tools/                 # 工具定义
│   ├── calculator.py      # 数学计算
│   ├── datetime_tools.py  # 时间工具
│   ├── file_tools.py      # 文件读写
│   ├── random_tools.py    # 随机数生成
│   ├── search.py          # 网页搜索
│   ├── text_tools.py      # 文本处理
│   └── url_tools.py       # URL 处理
├── agent/                 # 单 Agent + 工具调用
│   ├── api.py
│   ├── service.py
│   └── models.py
├── skillagent/            # 技能驱动 Agent
│   ├── api.py
│   ├── service.py
│   └── models.py
├── multiagent/            # 多 Agent 协作
│   ├── subagent/          # SubAgent 自动调度
│   └── supervisor/        # Supervisor 状态机
└── llm/                   # 直接 LLM 调用
    ├── api.py
    ├── service.py
    └── models.py

skills/                    # 技能定义（Markdown 文件）
├── coding/SKILL.md
├── web-research/SKILL.md
└── writing/SKILL.md
```

## 代码规范

- Python 3.14+，所有函数必须有类型注解
- 使用 ruff 检查：`uv run ruff check .`
- 格式化：双引号、100 字符行宽

## 测试

```bash
# 运行全部测试
uv run pytest tests/

# 运行单个测试文件
uv run pytest tests/test_agent.py

# 运行单个测试
uv run pytest tests/test_agent.py::test_agent_chat -v
```