《AgentX Python 专栏》03-架构篇：Agent 和「调个 API」的本质区别，在架构上长什么样？

📌 Python·反欺诈专栏第 3 篇（架构篇）｜系列：00 开篇 → 01 技术选型 → 📍02 架构 → 03 数据篇 →

上一篇： $技术选型篇：RAG 为什么不用 LangChain$ (《AgentX Python 专栏》02-技术选型篇：RAG 为什么不用 LangChain，而是选了 LlamaIndex？.md)

🏷️ 标签：#Python #金融反欺诈 #LangGraph #GraphRAG #Agent架构 #Neo4j #Text2Cypher

《AgentX Python 专栏》03-架构篇：Agent 和「调个 API」的本质区别，在架构上长什么样？

这是「用 Python 从 0 打造金融反欺诈 GraphRAG 智能体」专栏的第 3 篇。选型定了，这一篇讲整体架构怎么搭、每个设计为什么这么定------这也是 Agent 工程化和"调个 ChatGPT API"的真正分水岭。

本文速览

一个请求的完整旅程：从"P001 有风险吗"到带依据的回答
六层分层架构------每层职责 + 为什么这么分
🔥 核心：LangGraph 编排状态机------Agent 的灵魂，以及"跑崩了怎么办"
🌉 站在 Java 肩膀上：六层架构的迁移映射
4 个让它"像生产系统"的架构决策

一、先看一个请求的旅程

风控分析师问一句："申请人 P001 有欺诈风险吗？"

如果是"调个 API"，那就是 chat.completions.create("P001有风险吗") → 模型瞎编一通。它根本不知道 P001 是谁。

而在 AgentX-py 里，这个请求会走完这样一条链：

复制代码

抽出实体 P001 → 判断意图(风险查询) → 生成图查询 Cypher
  → 校验 + 交叉验证 → Neo4j 沿关系链检索（P001 和谁共用设备/担保）
  → 算风险特征（团伙规模/黑名单距离）→ LLM 结合证据解释
  → 护栏校验（引用的关系真实存在）→ 返回带依据的回答

差别就在这条链上 ：调 API 是"问一句答一句"，Agent 是"会规划、会查证、会兜底、答得有依据"。支撑这条链的，就是架构。

二、六层分层架构

层	职责	关键组件
接入层	收请求、校验、流式返回	FastAPI + Pydantic + SSE
编排层	Agent 大脑：决定下一步干什么	LangGraph 状态机
能力层	干活：检索 / 工具 / 记忆	LlamaIndex RAG、GraphRAG、工具系统
模型层	推理 + 向量化	Ollama / DeepSeek、bge-m3
存储层	存关系 + 会话	Neo4j（图+向量）、Redis
横切	贯穿全程：评测 + 可观测	Ragas / DeepEval、OTel / LangFuse

为什么分层？ 一句话：职责分离，换件不动全身。 想把 DeepSeek 换成别的模型？只动模型层。想加个新检索策略？只动能力层。编排层不关心"用哪个模型"，存储层不关心"谁在调它"。这是十几年工程养成的直觉------层与层之间靠接口说话，不靠耦合。

三、🔥 核心：LangGraph 编排状态机（Agent 的灵魂）

如果说六层是骨架，编排层就是灵魂。它决定了这东西是"智能体"还是"聊天机器人"。

它是一个状态机

我用 LangGraph 把整条链建成一个有向图------每个节点是一步操作，边是流转条件：

图中的三个关键路径：绿色 ✓ 为正常流程，橙色 ⟳ 为重试（≤N 次），红色 ✗ 为降级兜底。一条链三条路，每个节点职责明确------这才是生产级 Agent 编排该有的样子。

"跑崩了怎么办"------这才是面试官想看的

调 API 的人只想"怎么让它跑通"，做过生产的人想的是"它崩了怎么办"。这条链上我埋了三道防线：

重试：Text2Cypher 生成的 Cypher 不可靠（小模型尤甚），失败就重生成，最多 N 次；
降级：重试还不行，降级到预审过的参数化模板查询------保证至少能返回正确结果；
护栏：LLM 可能"语法对、语义错"或编造关系，最后用护栏校验引用的关系在图里真实存在，防幻觉。

💡 这套「条件路由 + 重试 + 降级 + 护栏」，就是 2026 AI 岗最高频的考点------"Agent 编排失败模式"。 LangGraph 的 add_conditional_edges + Checkpointer 让它落地得很自然。

四、🌉 站在 Java 肩膀上：架构迁移映射

我不是从零学 AI------我用 Java 自研过一套 Agent 框架（6644 行），这次是带着架构直觉转 Python。六层几乎一一对应：

Java 版 AgentX	AgentX-py	说明
Spring Boot Controller	FastAPI router	换语法
AgentService（调度）	service / 编排入口	换语法
AgentWorkflow（自研工作流）	LangGraph StateGraph	框架替代自研，更强
ToolRegistry + `@Tool`	`@tool` + registry	换语法
ChatMemory（Redis）	LangGraph Checkpointer	换包装
可观测（OTel+Jaeger）	同一套 OTel + Jaeger	底座直接复用

最关键的是 AgentWorkflow → LangGraph 这一映射：我自己写过工作流引擎，所以一眼看懂 LangGraph 在干什么------它就是把我手写的 while 循环 + 状态管理，封装成了更优雅的状态机 API。 框架不是黑魔法，是把你会的概念封装好。

五、4 个让它「像生产系统」的架构决策

光能跑不够，要"像能上线的系统"：

图 + 向量一个库（Neo4j 5 原生向量）------省掉单独维护 Milvus，架构更简。
双模型可切换 （Ollama / DeepSeek）------抽象统一接入层，私有化走本地、拼性能走 API，不依赖单点；主模型故障自动熔断降级到本地。
全链路可观测（OTel → Jaeger + LangFuse）------每个节点、每次 LLM 调用都埋点，"哪一步慢/错"一目了然（这是我 Java 版治"20 秒黑盒"练出来的肌肉记忆）。
异常体系 + 只读 DB 账号------统一错误响应；Neo4j 用只读账号连接，从数据库层杜绝 Cypher 注入（金融场景的安全底线）。

这些不是设计时拍脑袋想的------是这份架构经过两轮设计评审 + 迭代 打磨出来的（评审记录都在 GitHub 仓库里）。「设计 → 评审 → 修复」的闭环本身，比一份完美文档更能说明工程素养。

六、下一篇

架构图纸有了，下一篇就真正动手搭 ------《环境与底座 + Faker 造一套会"作弊"的数据》：Docker 起 Neo4j，用 Faker 造 2000 个申请人并故意植入欺诈团伙 ，让图数据库里真有"设备团伙、循环担保环"可查。代码跑起来，纸上架构才算活了。

🤝 写在最后：关于「关注」这件事

全网 AI 教程很多，但从架构设计、代码实现、真实踩坑到评测数据，一条龙带你做完一个工程级作品的系列，真的不多。这个系列，我会一篇篇认真更下去。

如果这篇对你有点用：

👍 点赞 + 收藏：让更多同路人刷到，也方便你回头查；
🔔 关注我 ：这是个长连载，关注了才不会错过后续------断了衔接就难接上了；
💬 评论区告诉我 ：你正在做 AI 转型吗？卡在哪一步？想优先看哪篇？------呼声高的我提前更；
📦 跟着做能攒出作品：每篇都带可复现的步骤，跟着走，你也能搭出属于自己的那一份。

我是 SuniaCoder（汪旭 / Sunia） ，一个 12 年的全栈老兵，正在记录自己的 AI 突围。

这里只写能落地、可复现的硬核实战 ------不灌水，不空谈。我们下一篇见。

评论区聊聊：你设计过最复杂的系统架构是什么？分层踩过哪些坑？