一个从零构建的 AI Agent 框架的设计与实现方案。框架采用服务与编排分离的 BaaS 架构，包含 Web UI 编排层、Agent 服务层及多种运行时环境（Python, WASM）。核心特性包括开放式编排、无限能力扩展及严格的安全沙箱机制。通过对比 Coze、Dify 等现有工具的局限性，阐述了自主构建框架的必要性。文章详细讲解了系统架构、协议设计、插件系统及执行流程，并提供了快速体验指南和安全优化建议，适用于需要深度定制和私有化部署的大模型应用场景。
随着大语言模型（LLM）能力的快速迭代，将 LLM 集成到具体业务应用中已成为技术趋势。最佳实践是将 LLM 封装为智能体（Agent），使其具备感知、规划、行动和反思的能力。本系列文章旨在从零开始构建一个高性能、可扩展的 AI Agent 框架，帮助开发者灵活构造和运行复杂的 Agent 应用。
在动手开发之前，有必要分析当前市场上主流的 Agent 编排框架，明确其优缺点及局限性。
Coze 是字节跳动推出的平台，以 Bot（Agent）为核心主体，集成了 RAG（检索增强生成）、Workflow（工作流）等功能。它支持 Single（单智能体）和 Multi（多智能体）两种模式。
Dify 可以被视为开源版的低配版 Coze，提供了类似的界面和基础功能，适合私有化部署，但在高级编排能力上仍有提升空间。
Stable Diffusion 生态中的 ComfyUI 提供了一种另类的 Workflow 设计理念。它基于节点图的形式，非常开放，支持任意流转，且能够导入导出。这种不拘一格的设计思路值得借鉴，特别是对于需要高度自定义流程的场景。
其他相关工具还包括 FlowiseAI、Kuafu、Boxcars 等，各有侧重，但大多存在范式固化或封闭的问题。
针对现有工具的不足，我们设计的 ai_agent 框架遵循以下核心目标：
整体架构划分为两个主要模块：Agent 服务（Agent Serve）和 Web UI。
![架构图示意]
Web UI 采用 WASM 技术构建编辑器，确保跨平台兼容性和高性能交互。用户在此界面定义插件视图和执行逻辑。编排后的结果是一个标准化的 JSON 格式的 Plan，包含节点定义、连接关系及参数配置。
这是框架的核心后端服务。它负责解析 Plan，管理生命周期，并协调各个运行时环境。
为了保障安全性和灵活性，框架引入了隔离的运行时环境。
项目依赖以下组件，请确保环境准备就绪：
docker run -itd -p 50001:50001 python_rt:latest
cd example
cargo run --bin serve
cd webui/server
go run main.go
cd webui trunk serve
## 加载插件
在 Web UI 中，可以通过 `Project -> LOAD` 从服务器端加载所有可用的 Plugin 插件。插件本质上是一组 JSON 配置文件，定义了节点的视图样式、输入输出参数及执行逻辑。
![插件加载示意图]
## 上传 Agent
可以直接上传预定义的 Agent 配置。将内容粘贴到 `plan-text-view` 窗口中，点击 `Upload Plugin` 按钮。系统将解析并展示所有的流程节点。
![流程节点示意图]
## 执行流程
打开 `Work-flow-view` 视图，可以观察 Single Agent 的执行流程。一个标准的流程总是以 `Start` 节点开始，以 `End` 节点结束。
典型执行逻辑如下：
1. **输入处理**：接收用户输入，初始化上下文。
2. **LLM 调用**：根据 Prompt 调用大语言模型生成初步响应。
3. **工具调用**：如果需要调用外部工具（如搜索、计算），则通过 Python RT 执行相应脚本，并将结果追加到 LLM 上下文中。
4. **循环迭代**：继续调用 LLM 进行下一轮推理，直到满足终止条件。
5. **返回结果**：流程结束，返回最终答案 `Answer`。
![执行流程图]
## 调试功能
框架内置了 Debug 模式。点击 `Debug` 按钮，可以查看关键流程节点的执行结果、输入输出数据及耗时统计，便于排查逻辑错误。
![调试界面示意图]
至此，一个简单的 Agent 流程体验完成。接下来我们将深入探讨核心实现细节。
# 核心实现细节
## 1. 编排协议设计
为了保证异构系统的兼容性，我们设计了轻量级的 Plan 协议。该协议基于 JSON Schema，定义了节点类型、属性、连接关系及变量传递规则。
```json
{
"nodes": [
{
"id": "node_1",
"type": "llm",
"config": { "model": "gpt-4", "prompt": "..." }
},
{
"id": "node_2",
"type": "python_script",
"config": { "code": "print('hello')" }
}
],
"edges": [
{ "from": "node_1", "to": "node_2" }
]
}
在执行用户提供的 Python 代码时，安全性至关重要。我们采用了以下措施：
插件系统支持热加载。开发者可以编写自定义插件并注册到系统中，无需重启服务。
Agent 执行可能涉及大量 I/O 操作。框架采用异步 IO 模型，结合连接池管理，提高吞吐量。
对于重复调用的 LLM 请求或工具结果，实施多级缓存策略，降低延迟和成本。
集成 Prometheus 和 Grafana，实时监控服务健康度、Token 消耗量及错误率，支持异常自动告警。
本框架通过解耦编排与执行，实现了高度的灵活性和可扩展性。相比现有的 SaaS 平台，它更适合对定制化要求高、需要私有化部署的企业级场景。
后续计划包括：
如果你不想使用复杂的 Web UI，也可以直接使用 Rust 编写代码，引用 agent_rt 和 wd_agent 库，通过编程方式体验框架能力。欢迎社区贡献代码，共同完善文档和功能。
Q: 如何自定义 LLM 适配器？
A: 实现标准的 ChatInterface 接口，注册到服务中即可。
Q: Python 沙箱是否支持安装第三方库？ A: 默认镜像仅包含基础库。如需额外依赖，需自行构建 Docker 镜像并替换运行时配置。
Q: 支持哪些数据库存储上下文？ A: 支持 Redis、PostgreSQL 等主流 KV 及关系型数据库，可通过配置切换。
通过上述设计，我们构建了一个既具备工业级稳定性，又拥有高度灵活性的 AI Agent 框架，为未来的智能化应用奠定了坚实基础。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online