Agent 架构设计：基于LangGraph的本地Agent架构

基于 LangGraph 的本地 Agent 架构设计

背景：AI 工程化的"集成墙"困局

大模型工程化落地已走过单点技术验证阶段。RAG 检索、智能记忆、工具调用、Agent 编排——每个独立模块都有成熟的开源实现。但当这些组件拼在一起跑生产时，集成墙问题集中爆发：

• RAG 检索到了精准文档，LLM 却优先使用自身内部知识回答，检索形同虚设
• 多节点工具调用结果在状态流转中丢失
• 跨会话用户记忆失效，每次对话都是"初次见面"
• 多轮对话上下文冗余溢出，Token 成本失控
• 第三方工具接入耦合度高，换个服务就得大改代码
• 系统无统一风控与观测体系，出了问题无从排查

这些问题不是单点技术能解决的——它们本质上是架构问题。本文以六大架构思维为准则，给出一个将 LangGraph、RAG、Memory、MCP 系统化整合的六层架构方案。

架构设计六大思维

在进入具体架构之前，先确立六条贯穿全文的设计原则。它们是区分"能跑的原型"和"能上生产系统"的关键分水岭。

1. 状态中心化思维

一切流转皆可追溯、可恢复。 摒弃传统无状态 API 开发思维，以 LangGraph State 为系统唯一数据流转载体。所有节点交互、工具调用、记忆检索、RAG 结果均统一归集至中心状态。通过标准化状态规约与持久化机制，实现服务重启、节点中断场景下的断点续跑。

2. 关注点分离思维

严格拆分流量接入、安全治理、流程编排、能力实现、数据存储、可观测六大层级。每层职责单一、边界清晰。RAG、记忆、工具等核心能力以插件化方式接入编排层，支持独立迭代、单独扩容、按需启停。

3. 能力标准化思维

基于 MCP（模型上下文协议）统一所有内外能力接入标准。本地函数、远程服务、数据库、知识库——全部走同一套协议。同时统一错误处理、超时熔断、权限校验、日志输出规范。

4. 分层容错思维

构建"接口层 → 编排层 → 能力层 → 数据层"四级容错体系。针对网络超时、检索失败、工具调用异常、LLM 输出解析错误、数据库宕机，配置差异化降级策略——熔断、重试、兜底、人工介入。

5. 成本性能平衡思维

摒弃无差别上下文灌入的粗放模式。通过上下文压缩、记忆分层、RAG 重排序、动态截断、模型分级调用等策略，精准平衡回答质量、Token 消耗、响应延迟三者关系。

6. 全链路可观测思维

每一次用户请求、每一轮节点执行、每一次检索与工具调用、每一次 LLM 推理——全链路追踪、指标统计、日志留存，形成"观测→分析→优化→迭代"的闭环。

一、架构总览：六层生产级弹性技术栈

传统四层架构（接入层、能力层、存储层、应用层）边界模糊、安全缺失、无观测体系。本文将其升级为六层生产级弹性技术栈：

各层职责

完整请求链路：

请求校验 → 记忆召回 → 查询优化 → 路由分发 → RAG 检索 → 工具调用 → 内容审核 → 应答输出

二、状态系统设计：LangGraph State 生产级规范

状态是 LangGraph 工作流的核心载体。原型项目中粗放的 State 设计是后期系统迭代困难、会话异常、故障无法恢复的根本原因。

核心设计原则

• 最小完备性：State 仅保留跨节点共享的核心数据，杜绝"上帝对象"。每个字段明确归属节点、更新时机、数据类型。
• 数据归约一致性：messages 等累积型数据必须使用框架内置归约器（如 add_messages），实现数据追加而非覆盖。
• 会话强隔离：以服务端生成的 thread_id 为唯一会话隔离标识，结合 user_id、tenant_id 实现三级隔离。核心隔离参数仅由服务端可信认证系统生成，禁止客户端自定义传入。
• 可序列化：所有状态字段采用可序列化数据结构，禁止存储临时对象、函数实例。

生产级 State 定义

from typing import Annotated, List, Optional, Literal, Dict, Any
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class GraphState(TypedDict):
    """生产级 LangGraph 中心状态：标准化、可持久化、可追溯"""

    # 多轮对话消息历史，归约器追加更新
    messages: Annotated[list, add_messages]

    # 用户原始输入与预处理后的标准化查询
    human_input: str
    refined_query: Optional[str]

    # 工作流路由决策字段
    next_node: Optional[Literal[
        "retrieve_memory", "retrieve_rag", "call_tool", "direct_answer"
    ]]

    # RAG 检索结果
    raw_retrieved_docs: List[dict]
    ranked_retrieved_docs: List[dict]

    # 分层记忆检索结果
    relevant_short_memory: List[dict]
    relevant_long_memory: List[dict]
    relevant_struct_memory: List[dict]

    # 工具调用数据
    tool_call_list: List[dict]
    tool_exec_results: List[dict]
    tool_error_info: Optional[str]

    # 人工审核与合规
    needs_human_approval: bool
    sensitive_check_result: str

    # 溯源与可观测
    node_execute_logs: List[dict]
    token_consumption: Dict[str, int]

    # 服务端可信配置（用户、会话、租户）
    runtime_config: Dict[str, Any]

持久化策略

需配置状态快照定时备份、过期会话自动清理、异常状态回滚机制，支持精准断点续跑。

三、分层记忆系统：模拟人类记忆机制

初级 AI 应用仅依赖单轮对话上下文——记忆易丢失、无个性化、跨会话即遗忘。生产级记忆系统需模拟人类"瞬时记忆—短期记忆—长期记忆"的分层机制。

三层记忆架构

L1 短期工作记忆（会话级）

• 存储位置：Redis 热层
• 生命周期：绑定当前会话 thread_id
• 策略：滑动窗口截断，保留最近 8-12 轮核心对话，自动过滤无效重复消息
• 特点：亚毫秒级读写，严控 Token 消耗

L2 结构化事实记忆（用户画像级）

• 存储位置：PostgreSQL
• 内容：用户身份、偏好设置、业务权限、常用操作、时区语言等结构化键值对
• 抽取方式：轻量信息抽取流水线，从对话中自动提取
• 特点：精准匹配查询，弥补向量检索无法精准匹配结构化数据的短板

L3 长期情节记忆（跨会话级）

• 存储位置：向量数据库冷层
• 内容：全量历史对话 → LLM 摘要压缩 → 向量化存储
• 召回方式：语义相似度检索，将 TopN 高相关记忆摘要注入会话提示词
• 特点：支持跨天、跨会话的智能延续；配置记忆过期与去重机制

三级存储分层

记忆优化策略

• 遗忘机制：自动淘汰低频、无效、过期记忆
• 合并机制：合并重复相似记忆片段
• 优先级排序：根据用户交互频次、业务重要性对记忆权重分级，优先加载高价值记忆

四、工业级 RAG 流水线：六阶全链路优化

传统简易 RAG 的"检索+拼接上下文"模式无法解决 LLM 忽略检索信息、编造答案的问题。本文构建六阶工业级 RAG 流水线：

六阶流程

查询预处理 → 多源混合检索 → 交叉编码器重排序 → 上下文压缩 → 强制溯源提示 → 答案校验

① 查询预处理与语义重写

对模糊、省略、指代性查询，通过轻量 LLM 完成语义补全、歧义消除、意图识别。将"那个东西怎么配？"这类上下文相关的模糊问句转化为精准检索语句。

② 多源混合检索

稠密向量检索（语义理解、模糊意图匹配）+ BM25 稀疏检索（关键词精准匹配、专业术语查询），加权融合两路结果。兼顾语义相关性与关键词精准度。

③ 交叉编码器重排序

对初筛 Top20 结果进行精细重排，过滤低相关、冗余、噪声文档，仅保留 Top5 核心优质片段。在保证信息完整性的前提下最小化 Token 消耗。

④ 上下文智能压缩

对重排序后的文档片段精简压缩，删除冗余语句、无效格式、重复内容，适配 LLM 上下文窗口限制。

⑤ 强制溯源提示工程

重构系统提示词，加入四大约束规则：

1. 强制引用：所有回答必须严格基于参考文档
2. 禁止编造：明确禁止臆造未知内容
3. 明确兜底：无匹配时回复"根据已知信息无法回答"
4. 来源标注：关键信息标注对应来源标识

⑥ 答案校验与脱敏

生成答案后反向校验内容是否完全匹配检索文档与用户需求，自动过滤敏感信息，修正逻辑偏差。

核心代码（Python 参考实现）

from langchain.retrievers import BM25Retriever, EnsembleRetriever
from langchain_community.vectorstores import Qdrant
from langchain_openai import OpenAIEmbeddings
from langchain_core.rerankers import CrossEncoderReranker

# 1. 初始化检索组件
embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

vector_store = Qdrant(
    url="your-qdrant-cluster-url",
    collection_name="enterprise-docs",
    embedding_function=embeddings
)
vector_retriever = vector_store.as_retriever(search_kwargs={"k": 20})

# BM25 稀疏检索
bm25_retriever = BM25Retriever.from_existing_index("enterprise-doc-index")

# 混合检索加权融合（向量 0.7 + BM25 0.3）
ensemble_retriever = EnsembleRetriever(
    retrievers=[vector_retriever, bm25_retriever],
    weights=[0.7, 0.3]
)

# 重排序模型
reranker = CrossEncoderReranker(model="cross-encoder/ms-marco-MiniLM-L-6-v2")

# 2. 标准化检索节点
async def rag_retrieve_node(state: GraphState) -> dict:
    query = state.get("refined_query") or state.get("human_input")

    # 混合检索初筛
    raw_docs = await ensemble_retriever.ainvoke(query)

    # 交叉编码器精排，取 Top5
    ranked_docs = reranker.rerank(query, raw_docs)[:5]

    # 标准化格式化，添加溯源标识
    formatted_docs = [
        f"[来源{i+1}] {doc.page_content}"
        for i, doc in enumerate(ranked_docs)
    ]

    return {
        "raw_retrieved_docs": raw_docs,
        "ranked_retrieved_docs": ranked_docs,
        "retrieved_docs": formatted_docs
    }

# 3. 生产级增强提示词构建
def build_production_prompt(state: GraphState) -> str:
    base_prompt = "你是企业级专业AI助手，回答必须精准、严谨、合规。\n"

    # 注入用户历史记忆
    if state.get("relevant_long_memory") or state.get("relevant_struct_memory"):
        memory_context = (
            state.get("relevant_long_memory", []) +
            state.get("relevant_struct_memory", [])
        )
        base_prompt += f"\n【用户历史背景信息】{memory_context}"

    # 注入检索文档与强制约束
    if state.get("retrieved_docs"):
        base_prompt += f"""
【权威参考文档】
{chr(10).join(state['retrieved_docs'])}

【强制回答规则】
(1) 所有回答必须严格基于上述参考文档与用户历史信息，禁止编造；
(2) 无匹配信息时，必须明确回复"根据已知信息无法回答该问题"；
(3) 回答需简洁精准，关键信息标注对应来源标识；
(4) 禁止输出与问题无关的冗余内容，严格规避信息幻觉。
"""
    return base_prompt

五、MCP 协议集成：标准化的能力接入体系

MCP（模型上下文协议）的核心价值在于解决传统工具集成的 N对N 耦合问题——每个工具服务端只需实现一次 MCP 标准接口，所有支持 MCP 的 Agent 均可直接调用。

MCP 核心价值

本地工具 vs MCP 远程工具

MCP 客户端单例落地要点

• 单例模式：避免连接频繁创建销毁
• 连接复用：客户端预热 + 连接池
• 异常重连：指数退避重试策略
• 超时控制：每次调用设置合理超时

六、LangGraph 高级编排：多模块协同工作流

基于前述状态设计、记忆系统、RAG 流水线、MCP 工具体系，通过 LangGraph 声明式状态图将所有离散能力编织为可循环、可分支、可审核、可恢复的完整智能工作流。

核心编排节点

编排关键设计

• 条件边动态路由：根据 next_node 字段决策流向，支持循环（工具调用后重新推理）
• 检查点机制（Checkpointer）：每个节点执行后自动保存状态快照
• 人工介入节点：needs_human_approval 触发时暂停流程，等待人工审核后继续
• 错误处理边：工具执行异常、LLM 调用失败自动走降级路径

七、生产级落地：部署、容错、观测、治理

高可用部署

• 容器化：Docker 打包 + K8s 集群编排
• 弹性扩缩：核心服务无状态化设计，支持 HPA 水平扩展
• 基础设施高可用：数据库、向量库、Redis 全部集群部署，主从备份 + 异地容灾
• 健康检查：就绪探针 + 存活探针，故障自愈

多级容错与降级

所有外部调用配置重试机制 + 指数退避，避免瞬时故障导致批量失败。

全链路可观测

安全与合规

• 双向内容过滤：输入输出同时过安全检测，拦截提示词注入、恶意提问、违规输出
• RBAC 权限模型：精细化管控用户对工具、知识库、记忆的访问权限
• 全流程审计：记录每次 LLM 调用、工具执行、记忆修改，支持合规审计
• 成本管控：精细化统计 Token 消耗，实现业务维度成本分摊

八、未来演进：从本地 Agent 到 A2A 联邦架构

当前架构解决的是单服务内多模块协同问题。当业务发展到多场景、多独立 Agent 时（例如：财务 Agent、人事 Agent、售后 Agent 各有自己的工具、提示词和流程），需要更进一步——A2A（Agent-to-Agent）联邦架构。

A2A 联邦架构的核心设计：

• 全局上下文中心 + 独立业务 Agent 双层设计
• 主调度 Agent 负责场景识别、路由分发，通过标准化 A2A 接口调用各独立服务
• 子 Agent 仅回传公共上下文变更，私有数据闭环留存
• 各业务 Agent 独立部署、独立迭代，互不影响

总结

本文构建的基于 LangGraph 的本地 Agent 架构方案，核心价值体现在三个维度：

1. 状态中心化管控 — 解决多节点流转数据丢失、上下文断裂问题，支持断点续跑
2. 分层智能记忆 — 实现真正的个性化、跨会话连续智能，从"每次初识"到"越聊越懂你"
3. MCP 标准化能力生态 — 彻底解决工具与数据源碎片化接入难题，能力可插拔、可扩展

配合全链路可观测、多级容错、安全治理体系，这套架构具备从原型到生产的完整闭环能力。下一步可基于现有骨架快速演进到 A2A 联邦架构，支撑多业务场景下的分布式 Agent 协同。