# ai_agent_example

**Repository Path**: hangcchhn/ai_agent_example

## Basic Information

- **Project Name**: ai_agent_example
- **Description**: AI Agent示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Agent 智能体学习项目

> 一个前后端一体的AI智能体学习项目，详细展示Agent的运作逻辑和工具调用过程

## 项目简介

本项目是一个教学性质的AI智能体应用，旨在帮助学习者理解：
- Agent的内部思考过程
- 工具调用的完整流程
- LangGraph状态机的运作方式
- 前后端实时通信的实现

## 技术栈

### 后端
- **FastAPI** - Python Web框架
- **LangChain** - Agent框架
- **LangGraph** - 状态图框架
- **OpenAI** - LLM客户端

### 前端
- **Vue 3** - 组合式API
- **TypeScript** - 类型安全
- **Element Plus** - UI组件库
- **Pinia** - 状态管理

## 功能特性

### Agent能力
- 🧠 智能思考 - 分析问题并制定解决方案
- 🔧 工具调用 - 支持搜索、代码执行、文件操作等
- 📊 过程可视化 - 完整展示思考步骤和工具调用
- 🔄 流式响应 - 实时推送Agent内部状态

### 可用工具
1. **Web搜索** - 使用Tavily API进行网络搜索
2. **代码执行** - 安全的Python代码执行
3. **文件操作** - 读写工作目录文件
4. **计算器** - 数学表达式计算
5. **日期时间** - 获取和格式化时间

## 快速开始

### 环境要求
- Python 3.12+
- Node.js 22+
- OpenAI兼容的API密钥

### 1. 克隆项目

```bash
git clone https://gitee.com/hangcchhn/ai_agent_example.git
cd ai_agent_example
```

### 2. 后端设置

```bash
# 进入后端目录
cd backend

# 创建虚拟环境（推荐）
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

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

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写你的 OPENAI_API_KEY

# 启动后端
python -m app.main
```

后端将在 `http://localhost:8000` 启动

### 3. 前端设置

```bash
# 打开新终端，进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端将在 `http://localhost:5173` 启动

### 4. 访问应用

打开浏览器访问 `http://localhost:5173`

## 项目结构

```
ai-agent-project/
├── backend/                # 后端服务
│   ├── app/               # 应用代码
│   ├── requirements.txt   # Python依赖
│   └── .env.example       # 环境变量示例
│
├── frontend/              # 前端应用
│   ├── src/              # 源代码
│   ├── package.json      # Node依赖
│   └── vite.config.ts    # Vite配置
│
└── README.md             # 本文件
```

## 使用示例

### 示例1：Web搜索

```
用户：帮我搜索一下Vue 3的最新版本

Agent思考：我需要搜索Vue 3的最新版本信息
工具调用：web_search(query="Vue 3 latest version")
Agent响应：根据搜索结果，Vue 3的最新版本是...
```

### 示例2：代码执行

```
用户：计算1到100的和

Agent思考：这是一个数学计算问题，可以用代码执行解决
工具调用：execute_code(code="print(sum(range(1, 101)))")
Agent响应：1到100的和是5050
```

### 示例3：文件操作

```
用户：创建一个文件hello.txt，内容是"Hello World"

Agent思考：用户需要创建文件并写入内容
工具调用：write_file(path="hello.txt", content="Hello World")
Agent响应：文件已成功创建
```

## 学习要点

### 1. LangGraph状态机
项目使用LangGraph构建Agent状态图，清晰展示决策流程：
- 思考节点 → 决定是否需要工具
- 工具节点 → 执行工具调用
- 响应节点 → 生成最终答案

### 2. 工具调用链
每个工具调用都完整展示：
- 调用参数
- 执行过程
- 返回结果
- 执行耗时

### 3. 实时通信
使用WebSocket推送Agent内部事件：
- 思考步骤
- 工具调用
- 状态变化

### 4. 可扩展性
添加新工具只需：
1. 使用`@tool`装饰器定义工具
2. 添加到工具列表
3. 前端自动展示

## 配置说明

### 必需配置
- `OPENAI_API_KEY` - 自定义OpenAI兼容的API密钥
- `OPENAI_BASE_URL` - 自定义OpenAI兼容的API端点
- `OPENAI_MODEL` - 自定义OpenAI兼容的OLLM模型

### 可选配置
- `TAVILY_API_KEY` - Web搜索功能（如不需要可省略）


详细配置请参考 `backend/.env.example`

## API文档

- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

## 开发指南

### 添加自定义工具

在 `backend/app/agent/tools.py` 中添加：

```python
from langchain.tools import tool

@tool
async def my_tool(param: str) -> str:
    """工具描述"""
    return "结果"
```

然后添加到 `get_available_tools()` 函数中。

### 自定义前端样式

修改 `frontend/src/assets/styles/main.css` 中的CSS变量。

## 故障排除

### 后端启动失败
- 检查Python版本是否>=3.12
- 确保所有依赖已安装
- 检查环境变量是否正确配置

### 前端连接失败
- 确保后端服务已启动
- 检查WebSocket连接配置
- 查看浏览器控制台错误信息

### 工具调用失败
- 检查对应API密钥是否配置
- 查看后端日志获取详细错误信息

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

如有问题请提交Issue。