# ChatAgent

**Repository Path**: hallo128/chat-agent

## Basic Information

- **Project Name**: ChatAgent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-09
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatAgent

基于 **LangGraph + FastAPI** 的 ReAct 模式智能对话 Agent，支持与桌面机器人等客户端通过 HTTP/JSON 通信。

## 架构设计

```
┌─────────────────────────────────────────────────────────────────────────┐
│ 终端交互层（客户端）                                                      │
│ 桌面机器人：发送请求、接收响应、及时反馈                                   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API 服务层                                                               │
│ FastAPI：异步接口、数据校验、鉴权、请求转发（HTTP/JSON）                   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Agent 核心层                                                             │
│ LangGraph：ReAct 工作流、工具循环调用                                     │
│ LangChain：提示词、工具封装、结构化输出                                   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 工具 / 数据支撑层                                                        │
│ 工具集：langchain_core.tools、MCP、Function Calling                      │
│ 可扩展：SearXNG、Mem0、Qdrant 等                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## 项目结构

```
ChatAgent/
├── src/
│   ├── agents/          # 智能体（Agent 层）
│   │   ├── prompts.py   # 提示词定义
│   │   ├── tools.py     # 工具集
│   │   └── chat_agent.py
│   ├── core/            # LLM 与配置
│   │   ├── config.py
│   │   └── llm.py
│   ├── service/         # FastAPI 服务
│   │   └── app.py
│   ├── schema/          # 结构化输出
│   │   └── chat.py
│   ├── client/          # 客户端
│   │   └── agent_client.py
│   ├── run_service.py   # 运行 API 服务
│   ├── run_client.py    # 运行 AgentClient
│   └── run_agent.py     # 直接运行 Agent
├── tests/
│   ├── agents/
│   ├── core/
│   ├── service/
│   ├── client/
│   └── schema/
├── requirements.txt
├── .env.example
└── README.md
```

## 虚拟环境

为防止与系统或其他项目环境冲突，建议使用虚拟环境。**推荐使用 Python 3.11**，与 LangGraph、LangChain、FastAPI 等依赖兼容性最佳。

### 创建虚拟环境

```bash
cd ChatAgent

# 使用 venv（Python 内置），推荐 Python 3.11
python3.11 -m venv .venv
# 若系统默认 python 已是 3.11，可直接: python -m venv .venv

# 或使用 conda
# conda create -n chatagent python=3.11
# conda activate chatagent
```

### 激活虚拟环境

```bash
# Linux / macOS
source .venv/bin/activate

# Windows (CMD)
# .venv\Scripts\activate.bat

# Windows (PowerShell)
# .venv\Scripts\Activate.ps1
```

激活后终端提示符前会显示 `(.venv)`，表示已进入虚拟环境。

### 退出虚拟环境

```bash
deactivate
```

---

## 快速开始

### 1. 安装依赖

在激活虚拟环境后执行：

```bash
cd ChatAgent
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 API Key 并设置 LLM_PROVIDER
```

**支持的 LLM 提供商**（均使用 OpenAI 兼容接口）：

| Provider | 说明 | 环境变量 | 默认模型 |
|----------|------|----------|----------|
| `openai` | OpenAI / Azure 等 | `OPENAI_API_KEY` | gpt-4o-mini |
| `deepseek` | DeepSeek | `DEEPSEEK_API_KEY` 或 `OPENAI_API_KEY` | deepseek-chat |
| `kimi` | Kimi / Moonshot | `MOONSHOT_API_KEY` 或 `OPENAI_API_KEY` | moonshot-v1-8k |
| `doubao` | 豆包 / 火山方舟 | `DOUBAO_API_KEY` 或 `OPENAI_API_KEY` | ep-xxx（需替换为接入点 ID） |
| `qwen` | 通义千问 / DashScope | `DASHSCOPE_API_KEY` 或 `OPENAI_API_KEY` | qwen-turbo |

示例：使用 DeepSeek
```env
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxx
# LLM_MODEL=deepseek-chat   # 可选，默认即为 deepseek-chat
```

### 3. 运行方式

**方式 A：API 服务 + 客户端（推荐，用于桌面机器人通信）**

```bash
# 终端 1：启动 API 服务
python -m src.run_service

# 终端 2：运行客户端测试
python -m src.run_client
```

**方式 B：直接运行 Agent（本地调试）**

```bash
python -m src.run_agent
# 或单次调用：python -m src.run_agent "今天几号？"
```

### 4. API 接口

| 接口       | 方法 | 说明           |
|------------|------|----------------|
| `/health`  | GET  | 健康检查       |
| `/chat`    | POST | 聊天接口       |

**请求示例：**

```bash
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "1+1等于几？"}'
```

**响应示例：**

```json
{
  "reply": "1+1 等于 2。",
  "session_id": null
}
```

## 工具扩展

默认工具：`get_current_time`、`calculator`、`echo`。  
在 `src/agents/tools.py` 中新增 `@tool` 装饰的函数即可扩展工具集。

后续可集成：
- MCP（`langchain_mcp_adapters`）
- SearXNG 联网搜索
- Mem0 / Qdrant 记忆存储

## 鉴权

在 `.env` 中设置：

```env
API_KEY=your-secret-key
REQUIRE_AUTH=true
```

请求时携带 Header：`X-API-Key: your-secret-key`。

## 测试

```bash
pytest
```

部分测试需真实 API Key，默认会跳过；可取消 `@pytest.mark.skip` 后运行集成测试。

## 技术栈

- **LangGraph**：ReAct 工作流
- **LangChain**：提示词、工具、LLM 封装
- **FastAPI**：异步 API
- **Pydantic**：数据校验与 Schema
- **httpx**：HTTP 客户端

## License

MIT