项目: reworkd/AgentGPT (35.8k⭐, 已归档)
定位: 浏览器端自主 AI Agent 组装、配置与部署平台
技术栈: Next.js 13 + FastAPI + LangChain + Prisma/SQLModel + MySQL
1. 系统总览与双层架构
AgentGPT 采用经典的前后端分离双层架构,前端负责 Agent 运行循环的编排与 UI 交互,后端负责 LLM 调用、工具执行和持久化。
┌─────────────────────────────────────────────────────┐
│ Frontend (Next.js 13 + TypeScript) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Zustand │ │ Agent │ │ Work Pipeline │ │
│ │ Stores │ │ RunModel │ │ (Work Items) │ │
│ └──────────┘ └──────────┘ └──────────────────┘ │
│ ↕ HTTP API calls │
├─────────────────────────────────────────────────────┤
│ Backend (FastAPI + Python) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Views │ │ Agent │ │ Tools │ │
│ │ (Router) │ │ Service │ │ (search/code/...)│ │
│ └──────────┘ └──────────┘ └──────────────────┘ │
│ ↕ LangChain → OpenAI API │
└─────────────────────────────────────────────────────┘
关键设计决策: Agent 的运行循环(autonomous loop)跑在浏览器前端,后端仅作为 LLM 代理和工具执行层。这意味着 Agent 的生命周期管理、任务队列、暂停/恢复逻辑全部由前端 TypeScript 代码控制。
2. Agent 运行循环(核心机制)
AgentGPT 的核心是一个 Work Pipeline 模式——AutonomousAgent 类维护一个 workLog(工作日志队列),按序执行工作单元。
// autonomous-agent.ts 核心循环
async run() {
this.model.setLifecycle("running");
this.addTasksIfWorklogEmpty();
while (this.workLog[0]) {
if (this.model.getLifecycle() === "pausing")
this.model.setLifecycle("paused");
if (this.model.getLifecycle() !== "running") return;
const work = this.workLog[0];
await this.runWork(work, () => this.model.getLifecycle() === "stopped");
this.workLog.shift();
await work.conclude();
const next = work.next();
if (next) this.workLog.push(next);
this.addTasksIfWorklogEmpty();
}
}
生命周期状态机: offline → running ⇄ pausing ⇄ paused → stopped
每个工作单元(AgentWork)是一个独立的步骤,执行完后可以通过 next() 链接下一个工作单元,形成流水线。初始工作单元是 StartGoalWork。
3. 工作单元模式(AgentWork 设计模式)
AgentGPT 定义了 7 种工作单元类型,每种封装一个原子操作:
| 工作单元 | 职责 | API 端点 |
|---|
|———|——|———|
StartGoalWork |
根据目标生成初始任务列表 | POST /api/agent/start |
|---|---|---|
CreateTaskWork |
根据执行结果生成后续任务 | POST /api/agent/create |
AnalyzeTaskWork |
分析任务,选择执行策略和工具 | POST /api/agent/analyze |
ExecuteTaskWork |
执行具体任务(流式输出) | POST /api/agent/execute |
SummarizeWork |
汇总所有执行结果 | POST /api/agent/summarize |
ChatWork |
与用户进行对话交互 | POST /api/agent/chat |
每个 Work 实现统一接口:
run(): 执行核心逻辑conclude(): 执行完成后的收尾工作(更新 UI、消息)next(): 返回下一个工作单元(链式编排)onError(): 错误处理回调
4. 前端状态管理(Zustand Store 体系)
前端使用 Zustand 进行状态管理,分为多个切片(Slice):
agentStore: Agent 实例引用、生命周期状态、思考状态、工具配置taskStore: 任务列表(started/completed 状态)、任务增删改messageStore: 消息流(Agent 与用户的对话记录)configStore: Agent 配置(名称、目标、迭代次数等)modelSettingsStore: 模型参数(temperature、model name 等)agentInputStore: 输入状态管理
AgentRunModel 是一个抽象层,将 Zustand store 封装为 Agent 运行所需的数据接口,使 AutonomousAgent 不直接依赖 UI 框架:
interface AgentRunModel {
getId(): string;
getGoal(): string;
getLifecycle(): AgentLifecycle;
getRemainingTasks(): Task[];
getCurrentTask(): Task | undefined;
updateTaskStatus(task: Task, status: TaskStatus): Task;
addTask(taskValue: string): void;
}
5. 后端 Agent 服务层
后端 FastAPI 提供 6 个 API 端点,每个端点对应一个 Agent 操作:
# views.py - 路由定义
router.post("/start") # 生成初始任务
router.post("/analyze") # 分析任务,选择工具
router.post("/execute") # 执行任务(支持流式)
router.post("/create") # 生成后续任务
router.post("/summarize") # 汇总结果(流式)
router.post("/chat") # 对话交互(流式)
AgentService 是核心服务类,通过 agent_service_provider 工厂函数创建,支持:
- 根据请求动态选择 LLM 模型(默认 GPT-3.5/4,汇总用 16k 版本)
- 流式响应(
StreamingResponse)用于执行、汇总、对话 - 依赖注入验证器(
dependancies.py)校验请求参数
6. 工具系统(Tool Architecture)
AgentGPT 后端实现了可扩展的工具系统,位于 platform/reworkd_platform/web/api/agent/tools/:
| 工具文件 | 功能 |
|---|
|———|——|
reason.py |
推理工具(纯 LLM 思考) |
|---|---|
search.py |
网络搜索(Serper API) |
sidsearch.py |
SID 搜索引擎 |
wikipedia_search.py |
Wikipedia 搜索 |
image.py |
图像生成(Replicate) |
code.py |
代码执行 |
conclude.py |
结论生成 |
open_ai_function.py |
OpenAI Function Calling 适配 |
工具选择机制: 前端 analyze 阶段会将用户激活的工具名称发送到后端,后端通过 Analysis 类型返回决策:
type Analysis = {
reasoning: string;
action: "reason" | "search" | "wikipedia" | "image" | "code";
arg: string;
};
后端根据 action 字段路由到对应的工具执行器。工具通过 tool.py 基类定义统一接口(available(), call(), public_description)。
7. LLM 集成与 LangChain
后端使用 LangChain 作为 LLM 抽象层:
model_factory.py: 工厂模式创建 LLM 实例,支持动态切换模型- Prompt 模板(
prompts.py): 定义各类任务的 prompt 模板 - 输出解析(
task_output_parser.py): 解析 LLM 输出为结构化任务列表 - 流式支持: execute/summarize/chat 端点返回
StreamingResponse
LangChain 的主要用途:
- Prompt 模板管理
- LLM 调用封装(支持 OpenAI、其他 provider)
- 输出解析(从 LLM 自由文本中提取结构化数据)
- 链式调用(Chain)
8. 数据库与认证
- ORM: 前端 Prisma(Next.js 侧)+ 后端 SQLModel(FastAPI 侧)
- 数据库: MySQL(通过 PlanetScale 托管,或 Docker 本地部署)
- 认证: NextAuth.js(前端会话管理),后端通过 session 校验用户身份
- 模型: Agent 配置、运行记录、用户数据等持久化到 MySQL
数据库 Schema 管理通过 Prisma migration 和 SQLModel 的 create_all 双轨并行。
9. 前端 UI 架构
前端采用 Next.js 13 App Router 风格(实际使用 Pages Router):
src/
├── components/ # React 组件(Dashboard, Chat, Task 等)
├── hooks/ # 自定义 hooks(useAgent, useTools 等)
├── services/ # 核心服务层
│ ├── agent/ # Agent 运行逻辑
│ ├── api/ # API 调用封装
│ └── workflow/ # 工作流定义
├── stores/ # Zustand 状态管理
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
└── ui/ # UI 原子组件
样式: TailwindCSS + HeadlessUI,schema 校验用 Zod(前端)+ Pydantic(后端)。
10. 架构评价与启示
优势
- 前端驱动的 Agent 循环: 运行状态完全在浏览器端管理,用户可实时观察、暂停、恢复 Agent
- Work Pipeline 模式: 将复杂 Agent 循环拆解为原子工作单元,可组合、可测试
- 双层解耦: 前端编排 + 后端执行,职责清晰
- 工具可扩展: 通过基类 + 工厂模式,新增工具只需实现接口
局限
- 前端循环的脆弱性: Agent 循环依赖浏览器保持打开,刷新即中断
- 无持久化运行: 运行状态仅存于内存和 localStorage,无法跨会话恢复
- 单 Agent 架构: 不支持多 Agent 协作或嵌套 Agent
- 工具选择简单: 基于单次 analyze 决策,不支持动态工具组合或链式工具调用
对 OpenMate 的启示
- Work Pipeline 模式值得借鉴——将 Agent 执行拆解为可组合的原子单元
- AgentRunModel 抽象层是好的设计——隔离 UI 状态与业务逻辑
- 前端驱动循环适合轻量场景,生产级系统应将循环移至后端
- 工具系统可参考其基类设计,但应支持更复杂的工具编排(MCP 协议)
*分析基于 AgentGPT main 分支源码,项目已于 2026-01-28 归档。*