# libagentcore

**Repository Path**: akinggw/libagentcore

## Basic Information

- **Project Name**: libagentcore
- **Description**: 一个基于c++实现的多agent系统，主要用于系统集成，相当于一个智能调度器，理解自然语言，然后将任务分配给不同的agent和相关工具干活，工具主要基于lua,类似于通过AI调度blender的效果。
- **Primary Language**: C++
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# libagentcore - 多Agent系统核心库

## 1. 系统功能与作用

libagentcore是一个基于大语言模型的多Agent协作系统核心库，旨在提供灵活、高效的智能体协作框架。该系统通过多个专门化的Agent协同工作，能够处理复杂的任务，如代码生成、问题求解、数据分析等。

### 核心功能

1. **多Agent协作**：支持多个专门化Agent（Planner、Worker等）协同完成任务
2. **任务规划与执行**：自动分解复杂任务，制定执行计划，并协调各Agent执行
3. **工具调用**：支持Lua脚本工具扩展，可动态加载和执行外部工具
4. **记忆管理**：基于向量数据库的长期记忆存储，支持语义检索
5. **模型推理**：集成llama.cpp推理引擎，支持多种量化模型
6. **多Token预测(MTP)**：支持Multi-Token Prediction加速推理

### 应用场景

- 自动化代码生成与重构
- 复杂问题求解与决策支持
- 数据分析与报告生成
- 智能对话与问答系统
- 自动化测试用例生成

## 2. 系统架构

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                    Application Layer                     │
│                  (GUI / CLI / API)                       │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                   TaskManager                            │
│         (任务调度、状态管理、结果收集)                     │
└──────────┬──────────────────────┬───────────────────────┘
           │                      │
┌──────────▼──────────┐  ┌───────▼────────────────────────┐
│   AgentManager       │  │   MemoryManager                │
│  (Agent生命周期管理)  │  │  (向量存储、语义检索)           │
└──────────┬──────────┘  └────────────────────────────────┘
           │
    ┌──────┴──────┬──────────────┐
    │             │              │
┌───▼────┐  ┌────▼─────┐  ┌────▼─────┐
│Planner │  │  Worker  │  │  Tool    │
│ Agent  │  │  Agent   │  │ Manager  │
└────────┘  └──────────┘  └──────────┘
    │             │              │
    └─────────────┴──────────────┘
                  │
         ┌────────▼────────┐
         │  ModelManager   │
         │ (llama.cpp推理) │
         └─────────────────┘
```

### 2.2 核心模块

#### Agent模块 (`includes/agent/`)
- **AgentManager**: 管理所有Agent的生命周期，负责Agent的创建、配置加载和销毁
- **BaseAgent**: Agent基类，定义Agent的基本接口和行为
- **PlannerAgent**: 规划Agent，负责任务分解和执行计划制定
- **WorkerAgent**: 工作Agent，负责具体任务的执行和工具调用

#### Task模块 (`includes/task/`)
- **TaskManager**: 任务管理器，负责任务提交、调度、状态跟踪和结果收集
- **Task**: 任务对象，封装任务输入、状态、执行结果等信息

#### Model模块 (`includes/model/`)
- **ModelManager**: 模型管理器，负责模型加载、推理接口封装
- 支持llama.cpp推理引擎，兼容GGUF格式模型
- 支持多种量化方案（Q4_K_M、Q4_K_XL等）
- 支持GPU加速（CUDA）和CPU推理

#### Tool模块 (`includes/tool/`)
- **ToolManager**: 工具管理器，负责工具加载、注册和调用
- **ScriptManager**: Lua脚本管理器，支持动态加载和执行Lua脚本
- 提供安全的沙箱环境，限制脚本权限

#### Memory模块 (`includes/memory/`)
- **MemoryManager**: 记忆管理器，基于SQLite向量扩展实现
- **EmbeddingModel**: 嵌入模型，用于文本向量化
- 支持语义检索，根据查询向量返回相关记忆

#### Core模块 (`includes/core/`)
- **Config**: 系统配置，包括模型路径、Agent配置、工具目录等
- **Log**: 日志系统，支持多级别日志输出和信号订阅

#### Commons模块 (`includes/commons/`)
- **ThreadPool**: 线程池，支持并发任务执行
- **Signal**: 信号槽机制，实现模块间松耦合通信
- **LuaBridge**: Lua绑定库，支持C++与Lua交互
- **SQLite-Vector**: SQLite向量扩展，支持向量存储和检索

### 2.3 数据流

```
用户输入
   │
   ▼
TaskManager.submit_task()
   │
   ├─► 创建Task对象
   │
   ├─► 提交到线程池
   │
   ▼
PlannerAgent.plan()
   │
   ├─► 分析任务
   │
   ├─► 查询记忆(MemoryManager)
   │
   ├─► 制定计划
   │
   ▼
WorkerAgent.execute()
   │
   ├─► 调用模型(ModelManager)
   │
   ├─► 调用工具(ToolManager)
   │
   ├─► 存储记忆(MemoryManager)
   │
   ▼
TaskResult
   │
   ▼
返回给用户
```

## 3. 编译说明

### 3.1 依赖项

#### 必需依赖
- **CMake** >= 3.16
- **C++17** 编译器（MSVC 2019+ / GCC 9+ / Clang 10+）
- **llama.cpp**：大语言模型推理引擎
- **ONNX Runtime**：嵌入模型推理

#### 可选依赖
- **CUDA** >= 11.8：GPU加速支持
- **wxWidgets** >= 3.2：GUI支持（测试程序）

### 3.2 编译步骤

#### Windows (MSVC)

```powershell
# 1. 配置CMake
cmake -B build -G "Visual Studio 17 2022" -A x64

# 2. 编译静态库
cmake --build build --config Release --target agentcore

# 3. 编译测试程序（可选）
cmake --build build --config Release --target agentcore_test
```

#### Linux (GCC/Clang)

```bash
# 1. 配置CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release

# 2. 编译静态库
cmake --build build --target agentcore

# 3. 编译测试程序（可选）
cmake --build build --target agentcore_test
```

### 3.3 输出产物

编译完成后，将在以下目录生成产物：

- **静态库**：`libagentcore/libs/agentcore.lib` (Windows) 或 `libagentcore/libs/libagentcore.a` (Linux)
- **测试程序**：`libagentcore/bin/agentcore_test.exe` (Windows) 或 `libagentcore/bin/agentcore_test` (Linux)

### 3.4 集成到项目

#### CMake集成

```cmake
# 添加libagentcore子目录
add_subdirectory(libagentcore)

# 链接静态库
target_link_libraries(your_target PRIVATE agentcore)

# 添加包含路径
target_include_directories(your_target PRIVATE
    ${CMAKE_SOURCE_DIR}/libagentcore/includes
)
```

#### 直接链接静态库

```cmake
# 添加包含路径
target_include_directories(your_target PRIVATE
    path/to/libagentcore/includes
)

# 链接静态库
target_link_libraries(your_target PRIVATE
    path/to/libagentcore/libs/agentcore.lib
    # 其他依赖库...
)
```

## 4. 使用示例

### 4.1 基本使用

```cpp
#include "task/task_manager.h"
#include "core/config.h"
#include <iostream>

using namespace agent;

int main() {
    // 1. 配置系统
    SystemConfig config;
    config.model_path = "models/Qwen3.5-4B-UD-Q4_K_XL.gguf";
    config.agents_dir = "agents";
    config.tools_dir = "tools";
    config.memory_db_path = "db/memory.db";
    config.thread_count = 4;
    
    // 2. 初始化TaskManager
    if (!TaskManager::instance().initialize(config)) {
        std::cerr << "初始化失败" << std::endl;
        return -1;
    }
    
    // 3. 提交任务
    std::string task_id = TaskManager::instance().submit_task(
        "请帮我写一个Python函数，计算斐波那契数列的第n项"
    );
    
    if (task_id.empty()) {
        std::cerr << "任务提交失败" << std::endl;
        return -1;
    }
    
    std::cout << "任务已提交，ID: " << task_id << std::endl;
    
    // 4. 等待任务完成
    while (true) {
        const TaskResult* result = TaskManager::instance().get_task_result(task_id);
        if (result && result->status == TaskStatus::Completed) {
            std::cout << "任务完成！" << std::endl;
            std::cout << "结果: " << result->output << std::endl;
            break;
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }
    
    // 5. 关闭系统
    TaskManager::instance().shutdown();
    
    return 0;
}
```

### 4.2 使用日志订阅

```cpp
#include "task/task_manager.h"
#include "core/config.h"
#include "commons/signal.hpp"

using namespace agent;

class MyLogHandler : public sigslot::has_slots<> {
public:
    void on_log(const std::string& msg) {
        std::cout << "[LOG] " << msg << std::endl;
    }
};

int main() {
    MyLogHandler handler;
    g_log_signal.connect(&handler, &MyLogHandler::on_log);
    
    SystemConfig config;
    TaskManager::instance().initialize(config);
    
    // 提交任务...
    std::string task_id = TaskManager::instance().submit_task("你的任务");
    
    // 日志会自动通过信号槽机制输出
    
    TaskManager::instance().shutdown();
    g_log_signal.disconnect(&handler);
    
    return 0;
}
```

### 4.3 查询Agent能力

```cpp
#include "agent/agent_manager.h"
#include "task/task_manager.h"

using namespace agent;

int main() {
    SystemConfig config;
    TaskManager::instance().initialize(config);
    
    // 获取所有Agent名称
    auto agent_names = AgentManager::instance().get_agent_names();
    std::cout << "可用Agent: ";
    for (const auto& name : agent_names) {
        std::cout << name << " ";
    }
    std::cout << std::endl;
    
    // 获取Agent能力描述
    auto capabilities = AgentManager::instance().get_capabilities();
    for (const auto& [name, desc] : capabilities) {
        std::cout << name << ": " << desc << std::endl;
    }
    
    TaskManager::instance().shutdown();
    return 0;
}
```

### 4.4 GUI应用示例

测试程序提供了一个完整的wxWidgets GUI示例，位于`libagentcore/test/`目录：

```cpp
#include <wx/wx.h>
#include "task/task_manager.h"
#include "commons/signal.hpp"

class MainFrame : public wxFrame, public sigslot::has_slots<> {
public:
    MainFrame() : wxFrame(nullptr, wxID_ANY, "Multi-Agent System") {
        // 创建UI控件
        auto panel = new wxPanel(this);
        auto sizer = new wxBoxSizer(wxVERTICAL);
        
        log_ctrl_ = new wxTextCtrl(panel, wxID_ANY, "",
            wxDefaultPosition, wxDefaultSize,
            wxTE_READONLY | wxTE_MULTILINE);
        
        input_ctrl_ = new wxTextCtrl(panel, wxID_ANY, "",
            wxDefaultPosition, wxDefaultSize,
            wxTE_PROCESS_ENTER);
        
        submit_btn_ = new wxButton(panel, wxID_ANY, "Submit");
        
        // 布局...
        
        // 绑定事件
        submit_btn_->Bind(wxEVT_BUTTON, &MainFrame::on_submit, this);
        
        // 订阅日志信号
        g_log_signal.connect(this, &MainFrame::on_log_message);
        
        // 初始化系统
        std::thread([this]() {
            SystemConfig config;
            TaskManager::instance().initialize(config);
        }).detach();
    }
    
private:
    void on_submit(wxCommandEvent& event) {
        wxString text = input_ctrl_->GetValue();
        std::string input = text.ToUTF8().data();
        TaskManager::instance().submit_task(input);
    }
    
    void on_log_message(const std::string& msg) {
        CallAfter([this, msg]() {
            log_ctrl_->AppendText(msg + "\n");
        });
    }
    
    wxTextCtrl* log_ctrl_;
    wxTextCtrl* input_ctrl_;
    wxButton* submit_btn_;
};

wxIMPLEMENT_APP(MyApp);
```

## 5. 配置说明

### 5.1 系统配置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_path` | string | "models/Qwen3.5-4B-UD-Q4_K_XL.gguf" | 模型文件路径 |
| `agents_dir` | string | "agents" | Agent配置目录 |
| `tools_dir` | string | "tools" | 工具脚本目录 |
| `memory_db_path` | string | "db/memory.db" | 记忆数据库路径 |
| `embedding_model_dir` | string | "models/bge" | 嵌入模型目录 |
| `thread_count` | int | -1 | 线程数（-1为自动检测） |
| `max_plan_rounds` | int | 5 | 最大规划轮数 |
| `max_result_rounds` | int | 3 | 最大结果生成轮数 |
| `script_timeout_ms` | int | 120000 | 脚本超时时间（毫秒） |
| `enable_mtp` | bool | true | 启用多Token预测加速 |

### 5.2 Agent配置

Agent配置文件位于`agents/`目录，每个Agent一个JSON文件：

```json
{
  "name": "code_generator",
  "type": "worker",
  "description": "代码生成Agent",
  "system_prompt": "你是一个专业的代码生成助手...",
  "tools": ["python_runner", "code_formatter"],
  "max_tokens": 2048,
  "temperature": 0.7
}
```

### 5.3 工具配置

工具脚本位于`tools/`目录，支持Lua脚本：

```lua
-- tools/math_helper.lua
function calculate(expression)
    return load("return " .. expression)()
end

function factorial(n)
    if n <= 1 then return 1 end
    return n * factorial(n - 1)
end
```

## 6. 性能优化

### 6.1 GPU加速

确保安装CUDA并正确配置环境变量：

```bash
export CUDA_HOME=/usr/local/cuda
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
```

### 6.2 多Token预测(MTP)

启用MTP可以显著提升推理速度：

```cpp
SystemConfig config;
config.enable_mtp = true;  // 启用MTP加速
```

### 6.3 线程池优化

根据CPU核心数调整线程数：

```cpp
config.thread_count = std::thread::hardware_concurrency();
```

## 7. 常见问题

### Q1: 编译时找不到llama.cpp库

确保llama.cpp已正确编译，并检查路径配置：

```cmake
set(LLAMA_BUILD_DIR "${CMAKE_SOURCE_DIR}/llama.cpp/build_cuda")
```

### Q2: 运行时找不到模型文件

检查模型路径是否正确，模型文件是否存在：

```cpp
config.model_path = "models/Qwen3.5-4B-UD-Q4_K_XL.gguf";
```

### Q3: 内存不足

尝试使用更小的量化模型或减少上下文长度：

```cpp
// 使用Q4_K_M量化模型
config.model_path = "models/Qwen3.5-4B-Q4_K_M.gguf";
```

## 8. 许可证

本项目采用MIT许可证，详见LICENSE文件。

## 9. 贡献指南

欢迎提交Issue和Pull Request。在提交PR前，请确保：

1. 代码风格一致
2. 通过所有测试
3. 添加必要的文档和注释

## 10. 联系方式

- 项目主页：[GitHub Repository]
- 问题反馈：[Issues]
- 文档：[Documentation]