Metadata-Version: 2.1
Name: LightAgent
Version: 0.1.2
Summary: A lightweight agent for Python
Home-page: https://github.com/wxai-space/LightAgent
License: Apache 2.0
Author: caiweige
Author-email: caiweige@qq.com
Requires-Python: >=3.10,<3.12
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: colorama (==0.4.6)
Requires-Dist: httpx (==0.28.1)
Requires-Dist: loguru (==0.7.3)
Requires-Dist: openai (==1.59.3)
Requires-Dist: requests (==2.32.3)
Project-URL: Repository, https://github.com/wxai-space/LightAgent
Description-Content-Type: text/markdown


![LightAgent Banner](docs/images/lightagent-banner.jpg)

<div align="center">
  <h1>LightAgent🚀（下一代Agentic AI框架）</h1>
</div>

**LightAgent** 是一个极其轻量的带记忆（`mem0`）、工具（`Tools`）、思维树（`ToT`）的主动式 Agentic Framework（自主性框架）。它支持类 Swarm 的多智能体协同、自动化工具生成、Agent 测评，底层模型支持 OpenAI、智谱 ChatGLM、百川大模型、DeepSeek、Qwen 系列大模型等。同时，LightAgent 支持 OpenAI 流格式 API 服务输出，无缝接入各大主流 Chat 框架。🌟

---

## ✨ 特性

- **轻量高效** 🚀：极简设计，快速部署，适合各种规模的应用场景。（No LangChain, No LlamaIndex）100% Python 实现，无需额外依赖，核心代码仅1000行，完全开源。 
- **记忆支持** 🧠：支持为每个用户自定义长期记忆，原生支持 `mem0` 记忆模块，实现对话过程中自动管理用户个性化记忆，让 Agent 更智能。
- **自主学习** 📚️：每个agent拥有自主学习能力，并且拥有权限的管理员可以管理每个agent。
- **工具集成** 🛠️：支持自定义工具（`Tools`），自动化工具生成，灵活扩展，满足多样化需求。  
- **复杂目标** 🌳：内置带反思的思维树（ToT）模块，支持复杂任务分解和多步推理，提升任务处理能力。  
- **多智能体协同** 🤖：比Swarm更简单实现的多智能体协同工作，内置LightSwarm实现意图判断和任务转移功能，能够更智能地处理用户输入，并根据需要将任务转移给其他代理。 
- **独立执行** 🤖：无人为干预自主完成任务工具调用。  
- **多模型支持** 🔄：兼容 OpenAI、智谱 ChatGLM、百川大模型、阶跃星辰、DeepSeek、Qwen 系列大模型。  
- **流式 API** 🌊：支持 OpenAI 流格式 API 服务输出，无缝接入主流 Chat 框架，提升用户体验。  

## 🚧 即将推出

- **Tools工具生成器** 🚀：只需将您的API文档交给[Tools工具生成器]，它将自动化地为您打造专属的tools，助您在短短1小时内快速构建数百个个性化的自定义工具，提升效率，释放您的创新潜能。
- **自适应tools机制** 🛠️：支持添加无限量tools，在上万个工具中让大模型先选取候选工具集合，过滤无关工具后再提交上下文给大模型，可大幅度降低Token消耗。
- **带记忆的智能体协同** 🛠️：智能体之间还可以共享信息和传递消息，实现复杂的任务协同。
- **agent自我学习** 🧠️：每个agent拥有自己的场景记忆能力，拥有从用户的对话中进行自我学习能力。
- **Agent 测评** 📊：内置 Agent 测评工具，方便评估和优化你构建的Agent，对齐业务场景，持续提升智能水平。  


## “思考流”
（Thought Flow）方法通过系统性、结构化和灵活的思维过程，能够有效应对复杂场景中的挑战。
 以下是具体实施步骤：
```text
问题定义：明确核心问题和目标。

信息收集：系统地收集相关信息和数据。

分解问题：将复杂问题分解为多个子问题或模块。

多维度分析：从不同角度和层面分析每个子问题。

建立关联：识别子问题之间的关联和依赖关系。

生成解决方案：针对每个子问题提出可能的解决方案。

评估与选择：评估各解决方案的可行性和影响，选择最优方案。

实施与反馈：实施选定方案，并根据反馈进行调整。
```

---
## 🌟 为什么选择 LightAgent？

- **开源免费** 💖：完全开源，社区驱动，持续更新，欢迎贡献！  
- **易于上手** 🎯：文档详尽，示例丰富，快速上手，轻松集成到你的项目中。  
- **社区支持** 👥：活跃的开发者社区，随时为你提供帮助和解答。  
- **高性能** ⚡：优化设计，高效运行，满足高并发场景需求。  

---

## 🛠️ 快速开始

### 安装LightAgent最新版本

```bash
pip install lightagent
```

（可选安装）通过 pip 安装 Mem0 包：

```bash
pip install mem0ai
```

或者，您可以通过一键点击在托管平台上使用 Mem0，[点击这里](https://www.mem0.ai/)。


### Hello world 示例代码

```python
from lightagent import LightAgent

# 初始化 Agent
agent = LightAgent(model="gpt-4o-mini", api_key="your_api_key", base_url= "your_base_url")

# 运行 Agent
response = agent.run("你好，你是谁？")
print(response)
```

### 通过system提示词设定模型自我认知

```python
from lightagent import LightAgent

# 初始化 Agent
agent = LightAgent(
     role="请记住你是LightAgent，一个可以帮助用户完成多工具使用的有用助手。",  # system角色描述
     model="deepseek-chat",  # 支持的模型：openai, chatglm, deepseek, qwen 等
     api_key="your_api_key",  # 替换为你的大模型服务商 API Key
     base_url="your_base_url",  # 替换为你的大模型服务商 api url
 )
# 运行 Agent
response = agent.run("请问你是谁？")
print(response)
```

### 使用工具示例代码

```python
from lightagent import LightAgent

# 初始化 Agent
agent = LightAgent(model="qwen-turbo-2024-11-01", api_key="your_api_key", base_url= "your_base_url")

# 定义工具
def get_weather(city_name: str) -> str:
    """
    Get the current weather for `city_name`
    """
    return f"查询结果: {city_name} 天气晴"
# 在函数内部定义工具信息
get_weather.tool_info = {
    "tool_name": "get_weather",
    "tool_description": "获取指定城市的当前天气信息",
    "tool_params": [
        {"name": "city_name", "description": "要查询的城市名称", "type": "string", "required": True},
    ]
}

# 运行 Agent
response = agent.run("请搜索最近关于大模型技术的新闻", tools=[get_weather])
print(response)
```
支持自定义无限数量的工具。

多个工具示例： tools=[get_weather, search_news, get_user_info, get_news]

---

## 功能详解

### 1. 可拆卸的全自动记忆模块（`mem0`）
LightAgent 支持外部扩展 `mem0` 记忆模块，全自动进行上下文记忆和历史记录管理，无需开发人员手动触发添加记忆和记忆查找。通过记忆模块，Agent 可以在多轮对话中保持上下文一致性。

```python
# 启用记忆模块

# 或者使用自定义记忆模块，下面以mem0为例 https://github.com/mem0ai/mem0/
from mem0 import Memory
from lightagent import LightAgent
import os
from loguru import logger

class CustomMemory:
    def __init__(self):
        self.memories = []
        os.environ["OPENAI_API_KEY"] = "your_api_key"
        os.environ["OPENAI_API_BASE"] = "your_base_url"
        # Initialize Mem0
        config = {
            "version": "v1.1"
        }
        # mem0中 如需使用qdrant作为向量数据库存储记忆，请将config改为下面代码
        # config = {
        #     "vector_store": {
        #         "provider": "qdrant",
        #         "config": {
        #             "host": "localhost",
        #             "port": 6333,
        #         }
        #     },
        #     "version": "v1.1"
        # }
        self.m = Memory.from_config(config_dict=config)

    def store(self, data: str, user_id):
        """存储记忆 开发者可以自行修改存储方法的内部实现，当前示例为mem0的添加记忆方法"""
        result = self.m.add(data, user_id=user_id)
        return result

    def retrieve(self, query: str, user_id):
        """检索相关记忆 开发者可以自行修改检索方法的内部实现，当前示例为mem0的查找记忆方法"""
        result = self.m.search(query, user_id=user_id)
        return result

agent = LightAgent(
        role="请记住你是LightAgent，一个可以帮助用户完成多工具使用的有用助手。",  # system角色描述
        model="deepseek-chat",  # 支持的模型：openai, chatglm, deepseek, qwen 等
        api_key="your_api_key",  # 替换为你的大模型服务商 API Key
        base_url="your_base_url",  # 替换为你的大模型服务商 api url
        memory=CustomMemory(),  # 启用记忆功能
        chain_of_thought=False,  # 启用思维链
    )

# 带记忆的测试 & 如果需要添加工具可以自行添加tools来实现带记忆的工具调用
tools = []
user_id = "user_01"
logger.info("\n=========== next conversation ===========")
query = "介绍下三亚的有什么好玩的景点，身边很多朋友都去三亚旅游了，我也想去玩"
print(agent.run(query, tools=tools, stream=False, user_id=user_id))
logger.info("\n=========== next conversation ===========")
query = "我想去哪里旅游呢？"
print(agent.run(query, tools=tools, stream=False, user_id=user_id))

```
输出如下：
```python
=========== next conversation ===========
2025-01-01 21:55:15.886 | INFO     | __main__:run_conversation:115 - 
开始思考问题: 介绍下三亚的有什么好玩的景点，身边很多朋友都去三亚旅游了，我也想去玩
2025-01-01 21:55:28.676 | INFO     | __main__:run_conversation:118 - Final Reply: 
三亚是中国海南省的一个热门旅游城市，以其美丽的海滩、热带气候和丰富的旅游资源而闻名。以下是一些三亚值得一游的景点：

1. **亚龙湾**：被誉为“东方夏威夷”，拥有绵长的沙滩和清澈的海水，是游泳、潜水和日光浴的理想之地。

2. **天涯海角**：这是一个著名的文化景观，以其壮丽的海景和浪漫的传说而吸引游客。这里的巨石上刻有“天涯”和“海角”字样，象征着永恒的爱情。

3. **南山文化旅游区**：这里有一个高达108米的南山海上观音像，是世界上最高的海上观音像。游客可以在这里体验佛教文化，参观寺庙和园林。

4. **蜈支洲岛**：这是一个小岛，以其原始的自然风光和丰富的水上活动而闻名。游客可以在这里进行潜水、浮潜、海钓等活动。

5. **大东海**：这是三亚市区内的一个海滩，以其便利的交通和丰富的夜生活而受到游客的喜爱。

6. **三亚湾**：这是一个长达22公里的海滩，是观赏日落的好地方。这里的海滩较为安静，适合喜欢宁静的游客。

7. **呀诺达雨林文化旅游区**：这是一个热带雨林公园，游客可以在这里体验热带雨林的自然风光，参与各种探险活动。

8. **鹿回头公园**：这是一个位于山顶的公园，可以俯瞰整个三亚市区和三亚湾的美景。这里还有一个关于鹿的美丽传说。

9. **西岛**：这是一个相对较为原始的小岛，以其宁静的海滩和丰富的海洋生物而吸引游客。

10. **三亚千古情**：这是一个大型的文化主题公园，通过表演和展览展示海南的历史和文化。

除了上述景点，三亚还有许多其他值得探索的地方，如热带植物园、海鲜市场等。三亚的美食也不容错过，尤其是新鲜的海鲜和热带水果。在规划旅行时，建议提前查看天气预报和景点开放时间，以确保有一个愉快的旅行体验。
2025-01-01 21:55:28.676 | INFO     | __main__:<module>:191 - 
=========== next conversation ===========
2025-01-01 21:55:28.676 | INFO     | __main__:run_conversation:115 - 
开始思考问题: 我想去哪里旅游呢？
发现相关记忆:
User wants to travel to Sanya
User's friends have traveled to Sanya。
2025-01-01 21:55:38.797 | INFO     | __main__:run_conversation:118 - Final Reply: 
根据用户之前提到的信息，用户的朋友已经去过三亚（Sanya），而用户自己也表达了对三亚的兴趣。因此，三亚可能是一个适合用户的旅游目的地。以下是一些关于三亚的旅游信息，供用户参考：

### 三亚旅游推荐：
1. **亚龙湾**：被誉为“东方夏威夷”，拥有美丽的海滩和清澈的海水，适合游泳和日光浴。
2. **天涯海角**：三亚的标志性景点，以其独特的岩石和浪漫的传说吸引游客。
3. **南山文化旅游区**：这里有著名的南山寺和108米高的海上观音像，是佛教文化的重要景点。
4. **蜈支洲岛**：适合潜水和海上运动，岛上有丰富的海洋生物和珊瑚礁。
5. **大东海**：三亚市区内的海滩，交通便利，适合家庭和情侣游玩。

### 其他推荐：
如果用户对三亚已经有所了解，或者想要探索其他目的地，以下是一些其他热门旅游地：
1. **桂林**：以其独特的喀斯特地貌和漓江风光闻名。
2. **丽江**：古城和玉龙雪山是其主要景点，适合喜欢历史文化和自然风光的游客。
3. **张家界**：以其奇特的石柱和自然景观著称，是《阿凡达》电影的取景地之一。

用户可以根据自己的兴趣和时间安排选择合适的旅游目的地。如果用户需要更详细的信息或帮助规划行程，请随时告知！
```

### 2. 工具集成（无限扩展的自定义工具支持）
拥抱个性化工具定制（`Tools`），并通过 `tools` 方法轻松集成您的专属工具。这些工具可以是任何Python函数，并且支持参数类型注解，以确保灵活性和精确性。此外，我们还提供智能AI驱动的工具生成器，助力您自动化构建工具，释放创造力。

```python

import requests
from lightagent import LightAgent

# 定义工具
def get_weather(
        city_name: str
) -> str:
    """
    获取城市天气信息
    :param city_name: 城市名称
    :return: 天气信息
    """
    if not isinstance(city_name, str):
        raise TypeError("City name must be a string")

    key_selection = {
        "current_condition": ["temp_C", "FeelsLikeC", "humidity", "weatherDesc", "observation_time"],
    }
    try:
        resp = requests.get(f"https://wttr.in/{city_name}?format=j1")
        resp.raise_for_status()
        resp = resp.json()
        ret = {k: {_v: resp[k][0][_v] for _v in v} for k, v in key_selection.items()}
    except:
        import traceback
        ret = "Error encountered while fetching weather data!\n" + traceback.format_exc()

    return str(ret)
# 在函数内部定义工具信息
get_weather.tool_info = {
    "tool_name": "get_weather",
    "tool_description": "获取指定城市的当前天气信息",
    "tool_params": [
        {"name": "city_name", "description": "要查询的城市名称", "type": "string", "required": True},
    ]
}

def search_news(
        keyword: str,
        max_results: int = 5
) -> str:
    """
    根据关键词搜索新闻
    :param keyword: 搜索关键词
    :param max_results: 返回的最大结果数量，默认为 5
    :return: 新闻搜索结果
    """
    results = f"通过搜索{keyword}, 我找到{max_results}条相关信息"
    return str(results)

# 在函数内部定义工具信息
search_news.tool_info = {
    "tool_name": "search_news",
    "tool_description": "根据关键词搜索新闻",
    "tool_params": [
        {"name": "keyword", "description": "搜索关键词", "type": "string", "required": True},
        {"name": "max_results", "description": "返回的最大结果数量", "type": "int", "required": False},
    ]
}

def get_user_info(
        user_id: str
) -> str:
    """
    获取用户信息
    :param user_id: 用户 ID
    :return: 用户信息
    """
    if not isinstance(user_id, str):
        raise TypeError("User ID must be a string")

    try:
        # 假设使用一个用户信息 API，这里用示例 URL
        url = f"https://api.example.com/users/{user_id}"
        response = requests.get(url)
        response.raise_for_status()
        user_data = response.json()
        user_info = {
            "name": user_data.get("name"),
            "email": user_data.get("email"),
            "created_at": user_data.get("created_at")
        }
    except:
        import traceback
        user_info = "Error encountered while fetching user data!\n" + traceback.format_exc()

    return str(user_info)

# 在函数内部定义工具信息
get_user_info.tool_info = {
    "tool_name": "get_user_info",
    "tool_description": "获取指定用户的信息",
    "tool_params": [
        {"name": "user_id", "description": "用户 ID", "type": "string", "required": True},
    ]
}

# 初始化 Agent
agent = LightAgent(model="qwen-turbo-2024-11-01", api_key="your_api_key", base_url= "your_base_url")

# 注册工具
tools = [get_weather, search_news, get_user_info]  # 包含所有工具

query = "当前三亚天气如何？"
response = agent.run(query, tools=tools, stream=False)  # 使用 agent 运行查询
print(response)
```

### 3. 思维树（ToT）
内置思维树模块，支持复杂任务分解和多步推理。通过思维树，Agent 可以更好地处理复杂任务。

```python
# 启用思维树
agent = LightAgent(
    model="qwen-turbo-2024-11-01", 
    api_key="your_api_key", 
    base_url= "your_base_url", 
    memory=True,  # 启用记忆功能
    tree_of_thought=True,  # 启用思维树
)
```

### 4. 多智能体协同
支持类 Swarm 的多智能体协同工作，提升任务处理效率。多个 Agent 可以协同完成复杂任务。

```python
# 创建多个 Agent
agent1 = LightAgent(model="chatglm")
agent2 = LightAgent(model="openai")

# 协同工作
response = agent1.collaborate(agent2, "请分析最近的市场趋势")
```

### 5. 多模型支持
兼容多种大模型，包括 OpenAI、智谱ChatGLM、DeepSeek、Qwen系列大模型。

#### 目前已经测试兼容的大模型
Openai系列
 - gpt-3.5-turbo
 - gpt-4
 - gpt-4o
 - gpt-4o-mini

Deepseek系列
 - DeepSeek-chat (API)
 - DeepSeekv2.5
 - DeepSeekv3

阶跃星辰
 - step-1-8k
 - step-1-32k
 - step-1-128k（在多工具调用中存在问题）
 - step-1-256k（在多工具调用中存在问题）
 - step-1-flash（推荐用此模型，性价比高）
 - step-2-16k（在多工具调用中存在问题）


Qwen系列
 - qwen-plus-2024-11-25
 - qwen-plus-2024-11-27
 - qwen-plus-latest 
 - qwen2.5-72b-instruct
 - qwen2.5-32b-instruct
 - qwen2.5-14b-instruct
 - qwen2.5-7b-instruct 
 - qwen-turbo-latest
 - qwen-turbo-2024-11-01
 - qwen-turbo
 - qwen-long

### 6. 流式 API (即将推出)
支持 OpenAI 流格式 API 服务输出，无缝接入主流 Chat 框架。

```python
# 启用流式输出
response = agent.run("请生成一篇关于 AI 的文章", stream=True)
for chunk in response:
    print(chunk)
```

### 7. Agent 测评 (即将推出)
内置 Agent 测评工具，方便评估和优化 Agent 性能。



---

## 使用场景

- **智能客服**：通过多轮对话和工具集成，提供高效的客户支持。
- **数据分析**：利用思维树和多智能体协同，处理复杂的数据分析任务。
- **自动化工具**：通过自动化工具生成，快速构建定制化工具。
- **教育辅助**：通过记忆模块和流式 API，提供个性化的学习体验。

---
 
## 🛠️ 贡献指南

我们欢迎任何形式的贡献！无论是代码、文档、测试还是反馈，都是对项目的巨大帮助。如果您有好的想法或发现 Bug，请提交 Issue 或 Pull Request。以下是贡献步骤：

1. **Fork 本项目**：点击右上角的 `Fork` 按钮，将项目复制到您的 GitHub 仓库。
2. **创建分支**：在本地创建您的开发分支：  
   ```bash
   git checkout -b feature/YourFeature
   ```
3. **提交更改**：完成开发后，提交您的更改：  
   ```bash
   git commit -m 'Add some feature'
   ```
4. **推送分支**：将分支推送到您的远程仓库：  
   ```bash
   git push origin feature/YourFeature
   ```
5. **提交 Pull Request**：在 GitHub 上提交 Pull Request，并描述您的更改内容。

我们会在第一时间审核您的贡献，感谢您的支持！❤️

---

## 🙏 致谢

LightAgent 的开发和实现离不开以下开源项目的启发和支持，特别感谢这些优秀的项目和团队：

- **mem0**：感谢 [mem0](https://github.com/mem0ai/mem0) 提供的记忆模块，为 LightAgent 的上下文管理提供了强大支持。  
- **Swarm**：感谢 [Swarm](https://github.com/openai/swarm) 提供的多智能体协同设计思路，为 LightAgent 的多智能体功能奠定了基础。  
- **ChatGLM3**：感谢 [ChatGLM3](https://github.com/THUDM/ChatGLM3) 提供的高性能中文大模型支持和设计灵感。  
- **Qwen**：感谢 [Qwen](https://github.com/QwenLM/Qwen) 提供的高性能中文大模型支持和设计灵感。  
- **DeepSeek-V3**：感谢 [DeepSeek-V3](https://github.com/deepseek-ai/DeepSeek-V3) 提供的高性能中文大模型支持。  

---

## 📄 许可证

LightAgent 采用 [Apache 2.0 许可证](LICENSE)。您可以自由使用、修改和分发本项目，但请遵守许可证条款。

---

## 📬 联系我们

如有任何问题或建议，欢迎随时联系我们：

- **邮箱**：156713035@qq.com  
- **GitHub Issues**：[https://github.com/wxai-space/lightagent/issues](https://github.com/wxai-space/lightagent/issues)  

我们期待您的反馈，一起让 LightAgent 变得更强大！🚀

- **更多工具** 🛠️：持续集成更多实用工具，满足更多场景需求。
- **更多模型支持** 🔄：持续扩展支持更多大模型，满足更多应用场景。
- **更多功能** 🎯：更多实用功能，持续更新，敬请期待！
- **更多文档** 📚：详尽文档，示例丰富，快速上手，轻松集成到你的项目中。
- **更多社区支持** 👥：活跃的开发者社区，随时为你提供帮助和解答。
- **更多性能优化** ⚡：持续优化性能，满足高并发场景需求。
- **更多开源贡献** 🌟：欢迎贡献代码，一起打造更好的 LightAgent！

---

<p align="center">
  <strong>LightAgent - 让智能更轻量，让未来更简单。</strong> 🌈
</p>

 
**LightAgent** —— 轻量、灵活、强大的主动式 Agent 框架，助您快速构建智能应用！
