跟着一个请求,走完所有层
讲架构最有效的方式 —— 不是讲概念,而是盯着一个具体请求,看它在每层发生了什么。
虚构场景
我们跟着这个问题走过整个 Agent 系统。 你会看到 5 层架构的每一层、每个环节实际在做什么。
💬 用户在聊天框打字
用户在 Gradio / Web 界面输入请求。前端做基础工作：消息排版、Markdown 渲染、流式显示。
🧭 拆解成可执行步骤
编排层(LangGraph)把这个模糊请求拆成子任务:
① 查京都 4 月樱花花期 → ② 规划 3 天路线 → ③ 推荐住宿 → ④ 计算预算
👥 多个 Agent 分工合作
专业 Agent 各自接活儿:
📅 行程 Agent 算时间 · 💰 预算 Agent 算钱 · 🏨 住宿 Agent 找酒店 · 🌸 攻略 Agent 查樱花情报
🧰 Agent 调用工具、查记忆
每个 Agent 需要数据时调用工具:
🔍 搜索工具查樱花时间 · 🌤️ 天气工具查 4 月天气 · 💾 记忆系统查用户偏好(上次说喜欢民宿)
🧠 真正调用 LLM 思考 + 记录一切
每条工具结果 → 喂给 GPT-4 / Claude / DeepSeek。
LangFuse 记录每一步:第几个 token、温度多少、调用哪个工具,方便后续调试。
📋 用户看到一份完整行程
所有 Agent 的结果汇集 → 编排层组织成报告 → 回流到第 1 层 → 用户看到一份包含行程、住宿、预算、樱花提示的完整方案。
💡 看到了吗？
没有一行代码,你也理解了 5 层各自干什么。
接下来,每层展开细看它在工程上由什么构成 —— 仍然少用代码,多用图示。
每一层的职责可视化
每层用一张可视化图形讲清它的角色 —— 由什么组成、对外提供什么、能解决什么问题。
第 1 层 · 用户体验
用户唯一直接接触到的层。它最简单,但最容易因为"丑/卡顿"被吐槽。
🎯 它主要解决 3 件事
🧰 选什么技术搭建
第 2 层 · 编排
系统的"调度中心"。把模糊请求拆成清晰步骤,决定下一步该让谁做什么。
🎯 它主要解决 3 件事
LLM 的判断力 ≈ "灵感",不可控、不易复现。
编排层把"灵感"落到"确定的状态机"上 —— 每一步明确、可追踪、可中断,出错了能从断点恢复。
第 3 层 · Agents
系统的"工人"。每个 Agent 是一种角色,擅长某个领域,有自己的 Prompt 和工具。
🎯 Agent 的关键设计原则
第 4 层 · 工具与记忆
Agent 的"手脚"和"长期记忆"。它让 Agent 不再只靠 LLM 的训练知识,而能触达真实世界的数据。
🎯 它主要解决 3 件事
第 5 层 · 基础设施
系统的"幕后"。没人直接操作,但没有它一切都跑不起来。
🎯 它主要解决 3 件事
代码落地:5 层 → 文件夹
可视化讲完每层后,用最简单的目录对应起来 —— 一个文件夹对应一层。
📂 一层对应一个文件夹
📁 agents/ → 第 3 层 (Master + Specialist)
master.py → 总控 Agent
researcher.py → 攻略 Agent
📁 orchestration/ → 第 2 层 (编排)
graph.py → LangGraph 状态机定义
state.py → 全局状态 schema
📁 tools/ → 第 4 层的一部分 (工具)
registry.py → 工具注册中心
📁 memory/ → 第 4 层的一部分 (记忆)
long_term.py → 向量数据库
📁 llm/ → 第 5 层 (模型调用)
📁 observability/ → 第 5 层 (监控)
📁 ui/ → 第 1 层 (Gradio)
🎯 这种组织的 3 个好处
5 阶段学习后,从 0 到 1阶段用直观的 5 层目录已经够清晰。
过度分层(端口适配器、六边形)会让你在第一次搭项目时就把 60% 时间花在文件夹结构上。
最后一步:让 Agent 上线
🖥 本地原型
最快的反馈循环。单用户、单 Agent。
- ▸
python main.py - ▸ Gradio → localhost:7860
- ▸ 无需考虑并发
🐳 Docker
一致环境、易分发。团队 / 小型生产。
- ▸
docker-compose up -d - ▸ 端口 80 一键启动
- ▸ 需要 HTTPS 时挂证书
☁️ 云端部署
可扩展、高可用。生产环境。
- ▸ Railway / Fly.io: 简单
- ▸ Modal / Replicate: GPU 推理
- ▸ AWS / GCP: 完全控制