从零开始构建 AI Agent 框架（一）：架构设计与快速体验

前言

将大语言模型（LLM）能力落地到具体应用中，最佳实践是将其封装为智能体（Agent）。本系列文章旨在从零开始编写一个 Agent 框架，帮助开发者高效地构造和运行复杂的 Agent 应用。

现有 Agent 编排框架探索

在动手开发之前，有必要分析现有的主流 Agent 编排工具。

Coze Coze 以 Bot（Agent）为核心，集成了 RAG、Workflow 等功能，支持 Single 和 Multi 模式。其优势在于上手简单，少量编辑即可搭建应用。但其编排能力相对受限，特别是在处理复杂思维链（CoT）场景时。Workflow 节点较为固定，不支持深度嵌入 Bot 内部逻辑，多 Bot 协作仅支持简单的 Multi-Agent 模式。不过，它支持 Workflow 嵌套 Workflow，扩展性较强。
Dify 可视为开源版的低配 Coze，提供了类似的编排界面和工作流功能。
其他工具 FlowiseAI、Kuafu、Boxcars 等也是常见的选择。
Stable Diffusion (ComfyUI) ComfyUI 提供了一种另类的 Workflow 思路，基于节点图流转，开放性强，支持导入导出，适合高度自定义的视觉生成任务。

设计目标

本 ai_agent 框架的设计目标如下：

编排式 Agent：不拘泥于单一范式，提供开放的编排能力，避免固定模式限制解决复杂问题的思路。
BaaS Solution：实现服务与编排分离，基于中间层协议通信。应用发布后，仅需调用服务 API 即可。
能力无限：Workflow 和 Agent 均可作为新 Agent 的子节点，支持递归和组合。

架构设计

系统主要划分为两个核心模块：Agent 服务和 WebUI。

WebUI：用于编排 Agent 的图形界面，编排结果生成执行计划（Plan）。
Agent Serve：Agent 服务层，负责加载各种 Service（如 LLM、Workflow 等），并根据 Plan 执行。
Python RT：Python 运行环境，允许直接执行 Python 代码作为 Service，未来将扩展 WASM Runtime 等。
Agent RT：Agent 运行时，是调度 Plan 的核心引擎。

Agent Framework Architecture Diagram

快速体验

启动服务

启动项目需要以下示例环境：

python_rt：用于远程调用 Python 并保证安全沙盒环境，版本使用 3.11.9。
webui：基于 WebAssembly 制作的编辑器，需要 Trunk 绑定。
OpenAI：默认使用 OpenAI 作为 LLM 提供商，需设置 AppKey 到环境变量。

# 启动 Python 运行时（已打包为 Docker，版本 3.11.9）
docker run -itd -p 50001:50001 wdshihaoren/python_rt:16896997

# 运行实例（启动 RPC 服务，能够运行 Plan）
cd example
cargo run --bin serve

# 运行 WebUI
cd webui/server
go run main.go

cd webui
trunk serve

加载插件

通过 project->LOAD 从 webui/server 中加载所有 Plugin 插件。插件本质是一组 JSON 文件，定义了插件的视图结构。

Plugin View Definition

此时可以通过拖拽节点制作 Workflow。

上传插件

可以直接上传一个做好的 Agent。将内容粘贴到 plan-text-view 窗口中，点击 upload plugin 上传，即可查看所有的流程节点。

Uploaded Agent Nodes

执行流程

打开 work-flow-view 视图，可以看到 Single Agent 的执行流程。

注意：一个流程总是以 start 节点开始，以 end 节点结束。

根据用户输入，调用 LLM。
如果需要调用 Tool，则用 Python 执行 Tool，将结果追加到 LLM 上下文中，继续调用 LLM。
如果不需要执行 Tool，则流程结束，返回答案 answer。

Execution Flow

Debug

点击 debug 按钮，查看关键流程的执行结果是否符合预期。

Debug Result

至此，一个简单的流程体验完成。

核心模块实现细节

为了深入理解框架原理，以下补充核心 Rust 库的实现细节。

1. Plan 定义结构

执行计划（Plan）采用 JSON 格式描述，包含节点列表及依赖关系。

{
  "nodes": [
    {
      "id": "node_1",
      "type": "llm",
      "config": { "model": "gpt-4", "prompt": "你好" }
    },
    {
      "id": "node_2",
      "type": "tool",
      "parent_id": "node_1",
      "config": { "name": "search", "args": ["query"] }
    }
  ]
}

2. Service Trait 接口

Agent 运行时通过统一的 Trait 接口调用各类服务。

pub trait Service {
    fn name(&self) -> &str;
    
    async fn execute(
        &self,
        context: &mut ExecutionContext,
        input: serde_json::Value,
    ) -> Result<serde_json::Value, AgentError>;
}

开发者只需实现该 Trait 即可注册新的 LLM 或 Tool 服务。

3. 安全沙箱机制

Python 运行时通过 Docker 容器隔离，限制网络访问和文件系统权限，防止恶意代码执行。

总结

本项目目前处于早期阶段，后续将完善文档并增加更多模块介绍。欢迎感兴趣的同学参与贡献。

如果不希望使用复杂的 WebUI，也可以直接使用 Rust 编程，引用 agent_rt 和 wd_agent crate，通过代码构建 Agent。

Custom Workflow Example

从零开始构建 AI Agent 框架（一）：架构设计与快速体验

前言

现有 Agent 编排框架探索

设计目标

架构设计

快速体验

启动服务

加载插件

上传插件

执行流程

Debug

核心模块实现细节

1. Plan 定义结构

2. Service Trait 接口

3. 安全沙箱机制

总结

更多推荐文章

相关免费在线工具

从零开始构建 AI Agent 框架（一）：架构设计与快速体验

前言

现有 Agent 编排框架探索

设计目标

架构设计

快速体验

启动服务

加载插件

上传插件

执行流程

Debug

核心模块实现细节

1. Plan 定义结构

2. Service Trait 接口

3. 安全沙箱机制

总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具