1. 系统功能与作用

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

核心功能

1. 多Agent协作：支持多个专门化Agent（Planner、Worker等）协同完成任务
2. 任务规划与执行：自动分解复杂任务，制定执行计划，并协调各Agent执行
3. 工具调用：支持工具扩展，应用层可通过Lua脚本（dukglue/luabridge）动态加载和执行外部工具
4. 记忆管理：基于向量数据库的长期记忆存储，支持语义检索
5. 模型推理：集成llama.cpp推理引擎，支持多种量化模型；同时支持OpenAI兼容HTTP API（如智谱GLM、OpenAI GPT等）
6. 多Token预测(MTP)：支持Multi-Token Prediction加速推理
7. 运行时模型切换：通过SystemConfig::use_http_model在本地模型和网络模型之间切换，无需重新编译

应用场景

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

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格式模型
• 支持OpenAI兼容HTTP API（通过libcurl），可在运行时切换
• 支持多种量化方案（Q4_K_M、Q4_K_XL等）
• 支持GPU加速（CUDA）和CPU推理
• 支持多种工具调用格式：Qwen3.5（peg-native）、Gemma4（peg-gemma4）、MiniCPM5等

Tool模块 (includes/tool/)

• ToolManager: 工具管理器，负责工具加载、注册和调用
• ScriptManager已解耦到应用层（test/drawer_lua），通过ToolManager的函数变量回调调用脚本
• 应用层负责集成dukglue/luabridge脚本引擎和efsw文件监控

Memory模块 (includes/memory/)

• MemoryManager: 记忆管理器，基于SQLite向量扩展实现
• EmbeddingModel: 嵌入模型，用于文本向量化
• 支持语义检索，根据查询向量返回相关记忆

Core模块 (includes/core/)

• Config: 系统配置，包括模型路径、Agent配置、工具目录等
• Log: 日志系统，支持多级别日志输出和信号订阅

Commons模块 (includes/commons/)

• ThreadPool: 线程池，支持并发任务执行
• Signal: 信号槽机制，实现模块间松耦合通信
• SQLite-Vector: SQLite向量扩展，支持向量存储和检索
• nlohmann::json: JSON处理库
• LuaBridge/dukglue/efsw已移至应用层，不在核心库中编译

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：嵌入模型推理
• libcurl：HTTP模型API支持（OpenAI兼容接口）

可选依赖

• CUDA>= 11.8：GPU加速支持
• wxWidgets>= 3.2：GUI支持（测试程序）
• GLEW+OpenGL：OpenGL绘制支持（drawer测试程序）
• dukglue+efsw：脚本引擎和文件监控（应用层依赖，非核心库）
• luabridge+Lua 5.4.7：Lua绑定库（应用层依赖，非核心库）

3.2 编译步骤

Windows (MSVC)

# 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 drawer_test cmake --build build --config Release --target calculator_test

Linux (GCC/Clang)

# 1. 配置CMake cmake -B build -DCMAKE_BUILD_TYPE=Release # 2. 编译静态库 cmake --build build --target agentcore # 3. 编译测试程序（可选） cmake --build build --target drawer_test cmake --build build --target calculator_test

3.3 输出产物

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

• 静态库：libagentcore/libs/agentcore.lib(Windows) 或libagentcore/libs/libagentcore.a(Linux)
• drawer_lua测试程序：bin/drawer_test.exe(Windows) - OpenGL绘制 + Lua脚本工具测试
• calculator测试程序：bin/calculator_test.exe(Windows) - 计算器测试

3.4 集成到项目

CMake集成

# 添加libagentcore子目录 add_subdirectory(libagentcore) # 链接静态库 target_link_libraries(your_target PRIVATE agentcore) # 添加包含路径 target_include_directories(your_target PRIVATE ${CMAKE_SOURCE_DIR}/libagentcore/includes )

直接链接静态库

# 添加包含路径 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 基本使用（本地模型）

#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 使用HTTP网络模型

#include "task/task_manager.h" #include "core/config.h" using namespace agent; int main() { SystemConfig config; // 切换为HTTP网络模型（OpenAI兼容API） config.use_http_model = true; config.api_url = "https://open.bigmodel.cn/api/paas/v4/chat/completions"; config.api_key = "your-api-key"; config.api_model = "glm-5"; // 也可使用环境变量：AGENT_API_URL / AGENT_API_KEY / AGENT_API_MODEL if (!TaskManager::instance().initialize(config)) { return -1; } std::string task_id = TaskManager::instance().submit_task("你好"); // ... TaskManager::instance().shutdown(); return 0; }

4.3 使用日志订阅

#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.4 查询Agent能力

#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.5 GUI应用示例

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

#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 系统配置参数

5.2 Agent配置

Agent配置文件位于agents/目录，每个Agent一个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脚本（应用层集成dukglue/luabridge）：

-- 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并正确配置环境变量：

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

6.2 多Token预测(MTP)

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

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

6.3 线程池优化

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

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

7. 常见问题

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

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

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

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

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

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

Q3: 内存不足

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

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

Q4: HTTP模型API调用失败

确保API地址、密钥和模型名称配置正确：

config.use_http_model = true; config.api_url = "https://open.bigmodel.cn/api/paas/v4/chat/completions"; config.api_key = "your-api-key"; config.api_model = "glm-5";

也可通过环境变量配置：AGENT_API_URL、AGENT_API_KEY、AGENT_API_MODEL

Q5: 如何在本地模型和网络模型之间切换

通过SystemConfig::use_http_model在运行时切换，无需重新编译：

// 使用本地模型 config.use_http_model = false; config.model_path = "models/Qwen3.5-4B-UD-Q4_K_XL.gguf"; // 使用网络模型 config.use_http_model = true; config.api_url = "https://api.openai.com/v1/chat/completions"; config.api_key = "sk-..."; config.api_model = "gpt-4o-mini";

8. 许可证

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

9. 贡献指南

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

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

截图预览