# JasperSoft Agent Learn

> AI Agent 开发学习项目 | 从零到一掌握 Agent 核心概念

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)

---

## 🎯 这是什么？

一个渐进式的 AI Agent 开发学习项目，通过 **5 个阶段（7 个主题）** 带你从零掌握 AI Agent 的核心概念：

| 阶段 | 主题 | 你将学会 |
|------|------|---------|
| Step 01 | Tool 工具系统 | 如何定义和注册工具 |
| Step 02 | State 状态管理 | 如何管理 Agent 的状态 |
| Step 03 | Simple Agent | 如何构建 Agent 循环 |
| Step 04 | Memory 记忆 | 如何让 Agent 记住对话 |
| Step 05~07 | RAG / Self-Correction / Multi-Agent | 进阶能力（同一目录） |

---

## 📚 学习大纲

### 第 1 周：基础（Step 01-03）
- Day 1-2: 理解 Tool 系统
- Day 3-4: 掌握 State 管理
- Day 5-7: 构建简单 Agent

### 第 2 周：进阶（Step 04 + 进阶包）
- Day 8-9: 多级记忆系统
- Day 10-11: RAG 与知识增强（Step 05）
- Day 12-13: 自我修正模式（Step 06）
- Day 14: 多 Agent 协作（Step 07）

---

## 🚀 快速开始

### 1. 克隆项目
```bash
git clone https://gitea.1415243231.top/panda/jaspersoft-agent-learn.git
cd jaspersoft-agent-learn
```

### 2. 安装依赖
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\activate   # Windows
pip install -r requirements.txt
```

### 3. 开始学习
```bash
cd step_01_tools
python main.py
```

---

## 📖 学习方法

每个 Step 都包含：

```
step_XX_name/
├── README.md              # 理论 + 架构图（先读）
├── concept.py             # 详细注释代码（再看）
├── exercise.py            # 练习题（自己做）
├── exercise_answer.py     # 参考答案（对照）
└── main.py               # 运行演示
```

---

## 💡 核心概念预览

### Tool（工具）
```python
class Tool:
    name: str          # 工具名称
    description: str  # 工具描述
    execute: Callable # 执行函数
```

### State（状态）
```python
state = {
    "messages": [...],   # 对话历史
    "context": {...},    # 上下文
    "memory": [...],     # 记忆
}
```

### Agent 循环
```python
while not done:
    thought = think(state)      # 思考
    action = decide(thought)    # 决策
    result = execute(action)    # 执行
    observe(state, result)      # 观察
```

---

## 🎓 学习目标

完成本项目后，你将能够：

- ✅ 理解 Tool 的定义和注册机制
- ✅ 掌握 State 的设计模式
- ✅ 能够构建简单的 Agent 循环
- ✅ 实现多级记忆系统
- ✅ 理解 RAG 架构（Step 05）
- ✅ 掌握 Self-Correction 模式（Step 06）
- ✅ 设计 Multi-Agent 协作系统（Step 07）

---

## 📝 项目结构

```
jaspersoft-agent-learn/
├── LEARN_GUIDE.md        # 详细学习指南
├── README.md             # 项目概览
├── .env.example          # 环境变量模板
│
├── step_01_tools/        # 工具系统
├── step_02_state/        # 状态管理
├── step_03_simple_agent/ # 简单 Agent
├── step_04_memory/       # 记忆系统
├── step_05_07_advanced/  # RAG（05）/ Self-Correction（06）/ Multi-Agent（07）
├── config.py             # 集中读取 .env（LLM key、RAG 路径等）
└── requirements.txt      # 可选依赖清单
```

---

## 🔗 相关链接

- 📂 **详细学习指南**: [LEARN_GUIDE.md](./LEARN_GUIDE.md)
- 🏠 **主项目**: [JasperSoft](https://gitea.1415243231.top/panda/jaspersoft)
- 📊 **日报系统**: [Daily On Work](https://gitea.1415243231.top)

---

## 🤝 参与贡献

欢迎提交 Issue 和 PR！

---

## 📄 许可证

MIT License

---

**开始你的 AI Agent 学习之旅吧！** 🚀