# simple_agent_framework

**Repository Path**: ybyedu/simple_agent_framework

## Basic Information

- **Project Name**: simple_agent_framework
- **Description**: 开发的一个简单的智能体
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简单智能体框架 (Simple Agent Framework)

一个用于学习和构建智能体的Python基础框架。通过这个框架，你可以了解智能体的核心概念和开发方法。

## 📚 文档

- **[📖 完整文档索引](./docs/INDEX.md)** - 查看所有项目文档
- **[🚀 快速开始](./docs/START_HERE.md)** - 从这里开始学习
- **[🔧 LangChain 集成](./docs/README_LANGCHAIN.md)** - LangChain 和大模型集成指南
- **[🎯 Skill 系统指南](./docs/SKILL_SYSTEM_GUIDE.md)** - 基于 Markdown 的技能定义和使用
- **[⚡ Skill 快速开始](./docs/QUICKSTART_SKILLS.md)** - 5分钟上手 Skill 系统

## 🆕 新特性：Skill 系统

本项目新增了 **Skill（技能）系统**，支持通过 Markdown 文件定义智能体的能力：

✅ **声明式定义**：用 Markdown + YAML 定义技能元数据  
✅ **解耦设计**：技能定义与执行逻辑分离  
✅ **渐进式披露**：动态加载技能详情，优化 Token 使用  
✅ **即插即用**：自动扫描 `skills/` 目录，无需修改代码  

### 快速体验 Skill 系统

```
# 运行交互式演示
python tests/demo_skills.py

# 或直接测试技能调用
python examples/example_skills.py

# 运行兼容性测试
python tests/test_skill_compatibility.py
```

查看 [docs/SKILL_SYSTEM_GUIDE.md](./docs/SKILL_SYSTEM_GUIDE.md) 了解如何创建自己的技能。

## 📁 目录结构

```
simple_agent_framework/
├── README.md                    # 项目主 README
├── docs/                        # 📚 文档目录
│   ├── INDEX.md                # 文档索引
│   ├── START_HERE.md           # 快速开始
│   ├── PROJECT_OVERVIEW.md     # 项目概览
│   ├── SKILL_SYSTEM_GUIDE.md   # 🆕 Skill 系统使用指南
│   ├── QUICKSTART_SKILLS.md    # 🆕 Skill 快速开始指南
│   ├── IMPLEMENTATION_SUMMARY.md  # 🆕 实现总结
│   └── ...                     # 其他详细文档
├── skills/                      # 🆕 技能定义目录
│   └── stock-price-skill/      # 示例技能：股票价格查询
│       ├── SKILL.md            # 技能定义
│       └── scripts/            # 执行脚本
├── examples/                    # 📝 示例代码目录
│   ├── README.md               # 示例说明
│   ├── example.py              # 基础功能示例
│   ├── quickstart.py           # 5分钟快速入门
│   ├── example_langchain.py    # LangChain 集成示例
│   ├── example_siliconflow.py  # 硅基流动集成示例
│   ├── example_skills.py       # Skill 系统示例
│   └── langchain_guide.py      # LangChain 配置指南
├── tests/                       # 🧪 测试文件目录
│   ├── README.md               # 测试说明
│   ├── test_*.py               # 单元测试文件
│   └── demo_*.py               # 演示脚本
├── __init__.py                 # 包初始化
├── agent.py                    # 智能体核心模块
├── message.py                  # 消息系统模块
├── tool.py                     # 工具系统模块
├── task.py                     # 任务管理模块
├── langchain_integration.py   # LangChain 集成模块
├── skill_loader.py             # 🆕 Skill 加载器
├── requirements_langchain.txt  # LangChain 依赖列表
└── .venv/                      # Python 虚拟环境
```

## 🎯 核心概念

### 1. 智能体 (Agent)
智能体是框架的核心，具有以下特性：
- **自主性**: 能够独立思考和响应
- **交互性**: 可以接收和发送消息
- **工具使用**: 能够使用各种工具完成任务
- **任务执行**: 可以接受并执行任务

### 2. 消息系统 (Message)
智能体之间的通信机制：
- 支持多种消息类型（文本、任务、响应、错误、系统）
- 包含发送者、接收者、时间戳等信息
- 维护消息历史

### 3. 工具系统 (Tool)
扩展智能体能力的工具：
- 计算器工具 - 执行数学计算
- 天气工具 - 查询天气信息（模拟）
- 搜索工具 - 检索信息（模拟）
- 可自定义扩展新工具

### 4. 任务管理 (Task)
任务的创建、分配和执行：
- 任务状态管理（待执行、执行中、已完成、失败、取消）
- 优先级设置
- 结果记录

## 🚀 快速开始

### 安装依赖

本框架无需外部依赖，只需Python 3.6+即可运行。

如需使用 LangChain 集成功能，请安装相关依赖：
```bash
pip install -r requirements_langchain.txt
```

### 运行示例

```
# 基础示例
python examples/example.py

# 快速入门
python examples/quickstart.py

# Skill 系统演示
python tests/demo_skills.py
```

这将运行各种示例，展示框架的不同功能。

## 💡 使用指南

### 1. 创建基础智能体

```
from simple_agent_framework import Agent, Message

# 创建智能体
assistant = Agent(
    name="小助手",
    role="通用助手",
    behavior="helpful"  # helpful, professional, 或 creative
)

# 发送消息
msg = Message(content="你好！", sender="user", receiver="小助手")
response = assistant.receive_message(msg)
print(response.content)
```

### 2. 为智能体添加工具

```
from simple_agent_framework.tool import CalculatorTool, WeatherTool

# 创建智能体
math_expert = Agent(name="数学专家", role="计算专家")

# 注册工具
math_expert.register_tool(CalculatorTool())

# 现在智能体可以使用计算器了
msg = Message(content="计算 5 + 3", sender="user")
response = math_expert.receive_message(msg)
```

### 3. 任务管理

```
from simple_agent_framework import Task

# 创建任务
task = Task("计算 10 + 20", priority=5)

# 分配任务给智能体
worker.assign_task(task)

# 执行任务
result = worker.execute_task(task)
print(f"任务结果: {result}")
print(f"任务状态: {task.status.value}")
```

### 4. 多智能体协作

```
# 创建多个专业智能体
coordinator = Agent(name="协调者", role="协调员")
calculator = Agent(name="计算员", role="计算专家")
calculator.register_tool(CalculatorTool())

# 协调者分派任务
calc_msg = Message(
    content="计算 15 + 27",
    sender="协调者",
    receiver="计算员"
)
calc_response = calculator.receive_message(calc_msg)
```

### 5. 添加知识库

```
# 为智能体添加知识
agent.add_knowledge("python", "Python是一种编程语言")
agent.add_knowledge("AI", "人工智能是计算机科学分支")

# 智能体会在对话中使用这些知识
```

## 🔧 自定义扩展

### 创建自定义工具

```
from simple_agent_framework.tool import Tool

class MyCustomTool(Tool):
    def __init__(self):
        super().__init__(
            name="my_tool",
            description="我的自定义工具"
        )
    
    def execute(self, *args, **kwargs):
        # 实现你的工具逻辑
        return "工具执行结果"

# 注册到智能体
agent.register_tool(MyCustomTool())
```

### 创建自定义智能体

```
from simple_agent_framework import BaseAgent, Message

class MyAgent(BaseAgent):
    def think(self, message: Message) -> str:
        # 实现你的思考逻辑
        return "我的响应"

# 使用自定义智能体
my_agent = MyAgent(name="我的智能体", role="特殊角色")
```

## 📖 学习路径

建议按以下顺序学习：

### 入门阶段
1. **运行快速入门** - 5分钟了解基本功能
   ```bash
   python examples/quickstart.py
   ```

2. **运行完整示例** - 观察框架的各种功能
   ```bash
   python examples/example.py
   ```

3. **阅读示例代码** - 理解示例中的实现细节
   - `examples/example.py` - 5个基础示例
   - `examples/quickstart.py` - 快速入门指南

### 进阶阶段
4. **探索核心模块** - 阅读各个模块的源代码
   - `agent.py` - 智能体核心逻辑
   - `message.py` - 消息系统
   - `tool.py` - 工具系统
   - `task.py` - 任务管理

5. **LangChain 集成** - 学习如何使用大模型
   ```bash
   python examples/example_langchain.py
   python examples/example_siliconflow.py
   ```

6. **Skill 系统** - 学习声明式技能定义
   ```bash
   python examples/example_skills.py
   python tests/demo_skills.py
   ```
   查看 [docs/SKILL_SYSTEM_GUIDE.md](./docs/SKILL_SYSTEM_GUIDE.md) 了解详情

### 高级阶段
7. **修改和实验** - 尝试修改示例代码
   - 改变智能体行为
   - 添加新的工具
   - 创建自己的智能体

8. **编写测试** - 学习如何测试你的代码
   ```bash
   python tests/test_skill_compatibility.py
   ```
   查看 [tests/README.md](./tests/README.md) 了解测试规范

9. **扩展框架** - 添加更多功能
   - 更复杂的推理逻辑
   - 持久化存储
   - 网络通信能力

## 🎓 智能体开发核心概念

### 感知-思考-行动循环
智能体通过以下循环工作：
1. **感知**: 接收消息或任务
2. **思考**: 分析输入，决定如何响应
3. **行动**: 生成响应或执行任务

### 工具增强
智能体本身能力有限，但可以通过工具扩展：
- 计算工具
- 查询工具
- 搜索工具
- 任何你需要的工具

### 多智能体协作
复杂任务可以由多个智能体协作完成：
- 协调者 - 分解任务
- 专家智能体 - 执行专业任务
- 汇总结果

## 🌟 进阶主题

当你掌握了基础知识后，可以尝试：

1. **集成真实API** - 连接真实的天气、搜索等服务
2. **机器学习集成** - 使用ML模型增强智能体决策
3. **持久化** - 保存智能体状态和历史
4. **并发处理** - 多智能体并行执行
5. **自然语言处理** - 集成NLP库提升理解能力

## 📝 项目结构说明

### 核心模块
- **agent.py**: 智能体基类和具体实现
- **message.py**: 定义消息格式和通信协议
- **tool.py**: 工具基类和示例工具
- **task.py**: 任务定义和状态管理
- **langchain_integration.py**: LangChain 与大模型集成
- **skill_loader.py**: Skill 系统加载器

### 示例代码（examples/）
- **example.py**: 完整的使用示例（5个示例）
- **quickstart.py**: 5分钟快速入门
- **example_langchain.py**: LangChain 集成示例
- **example_siliconflow.py**: 硅基流动平台集成
- **example_skills.py**: Skill 系统使用示例

### 测试文件（tests/）
- **test_*.py**: 单元测试文件
- **demo_*.py**: 演示脚本（无需 API Key）

每个模块都有详细的文档字符串，帮助你理解代码。

## 🤝 贡献

欢迎扩展这个框架！你可以：
- 添加新的工具类型
- 改进智能体的思考逻辑
- 增加更多的示例
- 完善文档

## 📄 许可证

本项目仅供学习和研究使用。

---

**祝你学习愉快！** 🎉

如有问题，请查看示例代码或阅读各模块的文档字符串。