新手做 AI 客服,千万别一上来就写“万能 Agent”

0 阅读17分钟

简单项目,简单拆解:一个「会分诊」的 AI 客服

​​

不是高深架构,就是把「该谁干」这件事分清楚——然后让它在线上别崩......

项目内容
🧰 技术栈FastAPI · LangGraph · SQLAlchemy 2.0 · PostgreSQL · Milvus · SSE
📖 难度会写 FastAPI 就能跟;LangGraph 从零讲
⏱ 阅读约 12 分钟,代码可直接抄
🎯 适合谁准备做第一个 AI 项目、或正被「万能 Agent」折磨的后端同学

hero-grid.png ​

封面:一条消息要走完的六步,全在这张图里


🧭 导读:这篇会带你走完什么

本节解决:先知道这篇文章能给你什么,再决定要不要往下读。

你会看到一句话剧透
为什么要分诊一个万能 Agent,等于让一个人兼任前台、部门经理和心理医生
架构长什么样主图路由 + 子图执行,Command 决定下一站
最容易踩的坑子图里加的字段,一回主图就「消失」
名词人话解释
Agent会自己安排工作的实习生:给目标,自己决定调什么工具、调几次
LangGraph给实习生画的流程看板:走到哪、下一步去哪、要记什么
RAG先翻资料再回答,而不是凭记忆瞎编
状态机一张写清「现在在哪、能去哪、要带什么」的表

💡 核心提示:AI 客服拼的不是模型多强,而是「谁该干这件事」的调度有多清楚。调度一乱,再贵的模型也只是更贵的混乱。


🚩 一、先认识四个词(以及一个被高估的词)

本节解决:把 Agent / LangGraph / RAG / 状态机 这四个词,翻译成你不查资料也能懂的话。

网上讲 Agent 的文章,十个里有八个先甩一堆英文缩写。我们先花 30 秒对齐一下——不是因为我严谨,是因为我当年也是被这些词劝退的那一批人。

名词人话解释在这个项目里干啥
Agent会自己安排工作的实习生:给目标,自己决定调什么工具用户问「怎么办」,它自己去查库、查文档
LangGraph给实习生画的流程看板:走到哪、下一步去哪、要记什么主图分诊,子图干活
RAG先翻资料再回答,而不是凭记忆瞎编问到细节,先检索原文再答
状态机一张写清「现在在哪、能去哪、要带什么」的表决定这轮进哪个子图、下轮还记不记得

状态机这词听着吓人,其实它就是一张表。你写 if/else 的时候其实也在做状态机,只是没画出来而已。

而被高估的那个词是 Prompt。它决定「话说得好不好听」, 但决定不了「该谁去说、说完记不记得」——那是架构的事。

📌 本节小结

  1. Agent 是「会自己选工具」的调用;
  2. LangGraph 是「把流程画出来」的框架;
  3. RAG 是「先查再答」;
  4. 状态机是「记着走到哪」的表。

🚨 二、需求拆解:先分诊,再干活

本节解决:为什么「一个万能 Agent」一定会失败,以及分诊制怎么救它。

最大的坑,是一上来就想「做一个万能 Agent」。

我试过:一段超长 Prompt,把所有规则写进去,让模型自己判断该干嘛。结果是——

  • Prompt 越写越长,改一句影响三句;
  • 意图互相串味,问资料的回答成了推荐;
  • 最要命的是出错了,完全不知道错在哪一步。

⚠️ 踩坑记录:那次失败的本质,是我把一个架构问题,写成了一个 Prompt 问题。Prompt 治不了架构病。

后来改成分诊制:一个轻量路由器判断意图,判断完把活儿交给对应的子流程。

窗口干什么特点
🔎 查资料先检索知识库,再组织语言依赖 RAG,答错代价高
🧾 办业务流程固定、步骤明确中途可能还要查用户信息
💬 闲聊纯聊天,不挂工具要能自然把话题引回业务

好处很直接:每个子流程能单独调试、单独改 Prompt、单独上线;路由错了也只是「进错窗口」,不会整个系统一起崩。

📌 本节小结 分诊制买到的不是「更聪明」,而是可调试性:错了知道错在哪一段。


🏗️ 三、骨架:三层结构 + 一个状态机

本节解决:代码该往哪放,资源该在哪初始化。

项目目录大概长这样:

app/
├── main.py                # 应用装配:启动、路由注册、异常处理
├── agents/                # 状态机与工具
│   ├── orchestrator.py    # 主图:分诊 + 挂载子图
│   ├── router.py          # 意图识别(规则 + 模型)
│   ├── tools.py           # Agent 能调用的工具
│   ├── schemas.py         # 状态定义
│   └── *_agent.py         # 三个子流程
├── modules/               # 业务模块:router / service / repository / schemas
├── rag/                   # 文档切分、入库、检索
└── infra/                 # 数据库会话、记忆存储

一句话分工:modules 管「数据怎么写」,agents 管「话怎么说」。两者之间只通过工具(Tool)这层耦合——哪天你想换一套意图识别方案,业务代码一行都不用动。

🧩 3.1 依赖注入:别自己 new 对象

这一节解决:为什么你的 session 和 graph 不该在函数里现造。

FastAPI 的 Depends 说白了就一句话:你不要自己创建对象,告诉框架你需要什么,它递给你。

像不像入职第一天?你以为电脑要自己配,结果 IT 早就放桌上了,只是没人告诉你线插哪。数据库会话和那张编译好的图,就是那台电脑——请求来了发一台,用完还回去。

from fastapi import APIRouter, Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession
​
router = APIRouter(prefix="/api/v1/chat", tags=["聊天模块"])
​
​
def get_service(
    request: Request,
    session: AsyncSession = Depends(get_session),          # 每个请求一个数据库会话
):
    return ChatService(session, request.app.state.agent)   # 整个应用共用一个编译好的图
​
​
@router.post("", response_class=EventSourceResponse)
async def chat(
    request: ChatRequest,
    user_id: Annotated[int, Header(alias="X-User-Id")],
    service: ChatService = Depends(get_service),
):
    ...

这里的两个设计点,都是被现实拷打出来的:

  1. 数据库会话是「请求级」的。get_session 大概是 async with AsyncSessionFactory() as session: yield session——yield 的意思是「用完请还我」,请求结束自动归还连接。Service 里永远不出现「新开一个 session」。
  2. 图是「应用级」的。整个服务只编译一次,挂在 app.state.agent 上。为什么不写成模块级全局变量?因为测试时你没法替换它,关停时你也没法释放它,而 app.state 是跟着应用生命周期走的。

💡 核心提示:判断一个后端写得好不好,看两点——资源从哪来、什么时候还。AI 项目也一样,只是多了几个「会喘气的资源」。

🚀 3.2 启动阶段:资源只留一个入口

这一节解决:启动顺序错了,报错会指向一个完全无关的地方。

@asynccontextmanager
async def life_span(app: FastAPI):
    await check_database()                                  # 1. 数据库探活
    checkpointer = await init_checkpointer()                # 2. 记忆存储:连池 + 建表
    app.state.agent = init_chat_graph(checkpointer)         # 3. 编译一次主图
    yield
    await close_database()                                  # 4. 逆序释放
    await close_checkpointer()

顺序有讲究:数据库不通就别去建记忆表;记忆存储没就绪,图也编译不完整(编译时会把存储绑上去)。

AI 应用的启动阶段比传统后端重得多:连接池、模型客户端、向量库客户端、图编译,全在这一步。把它收成一个入口,比散落在各个 import 里安全一万倍。

📌 本节小结 资源只留一个入口:lifespan 里按「数据库 → 存储 → 编译图」排,关停时逆序释放。


🚦 四、LangGraph:主图分工,子图干活

本节解决:一张图怎么变成「五个窗口」,以及节点怎么自己决定下一站。

整个过程画出来是这样:

architecture.png

图 1 · 主图分诊 + 五个出口,其中三个是子图

​

同一张图,用 Mermaid 表达是:

graph TD
    S([用户消息]) --> R[route 意图路由]
    R -->|consult| A[查资料子流程]
    R -->|service| B[办业务子流程]
    R -->|chitchat| C[闲聊子流程]
    R -->|human_handoff| D[转人工]
    R -->|fallback| E[兜底]
    A --> F([回复用户])
    B --> F
    C --> F
    D --> F
    E --> F

🧠 4.1 意图识别:先规则,再模型

这一节解决:哪些消息不该浪费一次模型调用。

最容易犯的错是「什么都交给模型」。像「你好」「谢谢」「再见」这种,正则匹配又快又免费,真没必要为它付一次模型调用。

    def match_social_intent(message: str) -> str | None:
        normalized = normalize_message(message)      # 去标点、转小写
        for intent, patterns in SOCIAL_PATTERNS.items():
            if any(re.fullmatch(p, normalized) for p in patterns):
                return intent
        return None

规则没命中的,再交给模型,而且要求它按结构返回,别返一段散文:

    class RouteResult(BaseModel):
        intent: Intent    # 固定几个取值之一
        reason: str       # 为什么这么判断,方便排查
    ​
    ​
    self.model = init_chat_model(...).with_structured_output(schema=RouteResult)

with_structured_output 的价值:后面拿到的就是对象,直接 .intent 用;要是让模型自由发挥,你就得写一堆字符串清洗,还得处理它偶尔「贴心地」加个句号。

💡 核心提示:能用 if 解决的,别开模型。模型是按次计费的,你写代码的时间也是。

🎫 4.2 Command:节点自己买票去下一站

这一节解决:为什么不用条件边,而让节点直接返回 Command。

传统写法是「节点返回状态 → 条件边决定去哪」。LangGraph 还给了另一种写法:节点直接返回一个 Command,里面既有状态更新,也写明下一站。

    async def route_node(state: ChatState):
        query = state["messages"][-1].content
        previous = state.get("active_workflow", "")
        result: RouteResult | str = await intent_router.route(query, f"上一轮流程:{previous}")
    ​
        if isinstance(result, str):        # 闲聊规则命中,直接给回复并结束
            return Command(
                update={"messages": [AIMessage(content=result)], "active_workflow": "chitchat"},
                goto=END,
            )
    ​
        return Command(
            update={"active_workflow": result.intent, "previous_workflow": previous},
            goto=result.intent,            # 跳转到同名节点
        )

有一个必须死守的约定:goto 的值和 add_node 注册的名字要一字不差。所以我把意图取值写成了 Literal[...],让「意图」和「节点名」共用一套词汇表。

⚠️ 踩坑记录:这类错误的特点是——编译器不管,运行时教你做人。名字少个字母,图照样编译,跑到那一步才炸。

路由的五个出口,状态转移长这样:

graph TD
    %% 定义节点样式:浅紫色底色,深色边框
    classDef default fill:#eef0ff,stroke:#d3d8ff,stroke-width:2px,color:#333;
    
    Start(( )) --> R[意图识别]
    
    R -->|consult| A[查资料子图]
    R -->|service| B[办业务子图]
    R -->|chitchat| C[闲聊子图]
    R -->|human_handoff| D[转人工]
    R -->|fallback| E[兜底回复]
    
    A --> End((( )))
    B --> End
    C --> End
    D --> End
    E --> End

🧱 4.3 主图装配

这一节解决:怎么把子图当积木插进主图。

    def init_graph(checkpointer):
        builder = StateGraph(ChatState)
    ​
        builder.add_node("route", route_node)
        builder.add_node("consult", init_consult_agent())      # 子图当节点用
        builder.add_node("service", init_service_agent())      # 子图当节点用
        builder.add_node("chitchat", init_chitchat_agent())    # 子图当节点用
        builder.add_node("human_handoff", handoff_node)        # 普通函数
        builder.add_node("fallback", fallback_node)
    ​
        builder.add_edge(START, "route")
        for node in ("consult", "service", "chitchat", "human_handoff", "fallback"):
            builder.add_edge(node, END)
    ​
        return builder.compile(checkpointer=checkpointer)

「子图也能当节点」 是这套架构最省事的地方:子图编译出来的东西,直接 add_node 挂上去,主图不用管它内部转了几圈。

三种子流程写法对比,新手照着选:

形态用在哪什么时候用
现成 Agent查资料标准「思考-调工具-再回答」
手搓 StateGraph办业务中间要插自己的逻辑
普通函数节点兜底确定性逻辑,不需要模型

选的标准很简单:能用现成就不手搓,需要干预就手搓,真不需要模型就别硬塞模型。

📌 本节小结 主图只做「分诊 + 收口」,具体活交给子图;子图编译产物直接当节点挂。


🗃️ 五、状态:AI 应用的隐形数据库

本节解决:为什么你的数据「明明写了却没生效」。

🧾 5.1 状态就是一个 TypedDict

这一节解决:messages 为什么是追加,其他字段为什么是覆盖。

    class ChatState(MessagesState):
        """主图状态"""
        previous_workflow: str
        active_workflow: str

MessagesState 是框架自带的,等于提前声明了 messages 字段。我第一次见它的时候以为是什么高科技,其实就是一个自带「消息列表」的 TypedDict(带类型的字典)。

但它有个不起眼的细节:messages 挂了一个叫 add_messages 的归约函数(reducer) 。意思是你往 messages 里写东西时,是追加,不是覆盖。


    # messages:追加(有 reducer 管着)
    return {"messages": [AIMessage(content=answer)]}

    # 其他普通字段:直接覆盖(默认语义)
    return {"active_workflow": "service"}

所以状态里每个字段都要问自己一句:这个字段被写的时候,是覆盖还是追加? 想追加就得显式声明 reducer,默认都是覆盖。

🕳️ 5.2 子图里加的字段,为什么会「消失」

这一节是全文最值钱的一段:一个不报错、只丢数据的坑。

这个坑我卡了半天,值得单独说。

闲聊子图想做个限制:连续闲聊超过 3 次就提醒用户回业务。于是我在子图状态里加了个计数:

    class ChitchatState(ChatState):
        chitchat_count: int    # 子图内部计数

结果:子图里明明能读到、能自增,一回到主图就没了,下一轮又从 0 开始。

最气的是它不报错,只是默默忘记。

原因其实不玄乎:子图执行完,输出要投影回主图,而投影只认主图状态里声明过的字段。父图压根不认识 chitchat_count,它就被丢掉了。

⚠️ 踩坑记录:想跨轮次活下来的数据,必须声明在父图状态里;子图只放「本次流程内的临时变量」。

顺便说一个同源的问题:节点返回值必须是 dict。习惯了 Pydantic 的话很容易直接 return 某个对象,框架会报状态更新错误——要么返回 dict,要么先 .model_dump()。

🧵 5.3 多轮记忆,其实只有一行代码

这一节解决:为什么「换个会话就失忆」。


    config = {"configurable": {"thread_id": str(request.thread_id)}}
    async for event in self.agent.astream_events(
        {"messages": [HumanMessage(content=request.message)]}, config
    ):
        ...

thread_id 一样,就是同一个会话的记忆;配上 PostgreSQL 版的存储(AsyncPostgresSaver),每一步状态都落库。

我们让业务表的主键直接当 thread_id,于是两件事分开管:

  • 用户隔离用 SQL 做(WHERE user_id = ?);
  • 记忆隔离用 thread_id 做(框架负责)。

分工清楚了,代码就清爽了。

📌 本节小结

  1. 跨轮数据必须在父图声明;
  2. 节点返回 dict,不是对象;
  3. 记忆隔离靠 thread_id,一行配置。

🔍 六、RAG:把「查资料」做成一个工具

本节解决:RAG 该写进流程,还是该交给模型自己决定什么时候查。

对新手来说,RAG 最反直觉的一点是:它不该是流程里固定的一步,而应该是 Agent 手里的一个工具。

区别在哪?流程固定的话,无论用户问什么都要先检索一遍,浪费钱也浪费时间;做成工具之后,什么时候查、查几次、要不要换个关键词再查,交给模型判断。

📚 6.1 父块 + 子块

这一节解决:文档切小了没上下文、切大了搜不准,怎么办。

一份业务文档动辄几十页。切小块,检索准但上下文碎;切大块,上下文全但检索不准。解法是切两层:

  • 父块:按 Markdown 标题层级切,保留完整章节,存关系库;
  • 子块:父块再按 500 字递归切,带上 parent_id,存向量库。

检索时先命中子块,再顺着 parent_id 批量取回父块——小块负责找准,大块负责讲全。

🎯 6.2 混合检索:向量 + 关键词

这一节解决:为什么只上向量还不够。

    vector_store = Milvus(
        embeddings,                                     # 稠密向量
        collection_name="docs_v1",
        builtin_function=BM25BuiltInFunction(
            analyzer_params={"type": "chinese"},        # 中文分词的稀疏检索
        ),
        vector_field=["dense", "sparse"],               # 两路一起召回
        auto_id=True,
    )

为啥要两路?向量擅长「意思相近」,但用户问「第三点第二条写的啥」这种精确表述时,关键词检索反而更稳。两路召回后再上一道精排(rerank),把真正相关的段落顶到前面。

💡 核心提示:检索质量决定回答质量的上限,Prompt 只能决定下限。别指望用提示词治好检索的病。

🛡️ 6.3 工具 + 防幻觉提示词

这一节解决:怎么让模型「只照着资料说」。


    @tool
    async def query_knowledge(doc_id: str, query: str):
        """根据文档 ID 和问题,取回相关章节原文"""
        chunks = await retriever.retrieve(doc_id, query, 5)
        return "\n\n".join(
            f"章节:{'>'.join(c.section_path)}\n内容:{c.content}" for c in chunks
        )

再配合系统提示词里写死的约束:

- 回答具体细节前,必须先调用 query_knowledge,再根据检索结果回答。
- 只能基于检索到的内容回答,不要编造;没查到就如实告知。

工具负责「拿得到」,Prompt 负责「用得上」。 只写 Prompt 不给工具,模型只能编;只给工具不写约束,模型可能懒得查。

📌 本节小结 RAG 是「止疼药」不是「万能药」:能缓解幻觉,治不了胡说。


⌨️ 七、流式:把打字机体验还给用户

本节解决:为什么用户宁愿等 3 秒看字一个个出来,也不愿等 3 秒看一次全屏刷新。

聊天界面要是等整段生成完再一次性吐出来,体验会很难受。SSE(Server-Sent Events)就是干这个的:一个连接,服务器单向往外推,浏览器原生支持。

一次请求从头到尾长这样:

sequenceDiagram
    autonumber
    participant B as 浏览器
    participant F as FastAPI
    participant L as LangGraph
    participant M as 模型

    B->>F: POST /api/v1/chat (X-User-Id)
    
    Note right of F: 校验会话归属
    
    F->>L: astream_events (thread_id)
    
    Note right of L: route 判断意图
    
    L->>M: 发起生成
    M-->>L: token 流
    
    L-->>F: on_chat_model_stream
    F-->>B: SSE data: token
    F-->>B: SSE event: done

先看接口这一层,只做一件事:把 Service 的流透传出去。

    @router.post("", response_class=EventSourceResponse)
    async def chat(request: ChatRequest, service: ChatService = Depends(get_service)):
        async for event in service.chat_stream(request):
            yield event

Service 里只挑「模型正在吐字」的事件往外发:

    async def chat_stream(self, request: ChatRequest):
        config = {"configurable": {"thread_id": request.thread_id}}

        async for event in self.agent.astream_events(
            {"messages": [HumanMessage(content=request.message)]},
            config,
            version="v2",
        ):
            if event["event"] != "on_chat_model_stream":
                continue
            chunk = event["data"].get("chunk")
            text = getattr(chunk, "content", "")
            if text:
                yield ServerSentEvent(data=text, event="message")

        yield ServerSentEvent(data="", event="done")     # 明确收尾

三条经验:

  1. astream_events 是异步生成器,不能 await。写成 await agent.astream_events(...) 会直接报 TypeError,正确姿势是 async for。
  2. 只转发 on_chat_model_stream。框架事件流很丰富(节点开始、工具调用、结束……),全转发等于把内部实现暴露给前端。
  3. 发一个 done 事件。前端收到就关掉「正在输入」,比靠连接断开去猜靠谱。

📌 本节小结 用户不关心你的架构,只关心字出没出来。


🚧 八、新手最容易踩的几个坑

本节解决:把别人的跟头,变成你的检查清单。

下面六条,我中过四条。剩下两条没中,纯粹是运气。

坑现象怎么解
子图字段不持久计数下一轮归零声明在父图状态里
节点返回对象状态更新报错返回 dict / .model_dump()
astream_events 被 awaitTypeError: async_generator改用 async for
异常处理器一把抓404 也变 500每类异常单独注册
router 注册两次文档里重复接口include_router 只调一次
Prompt 要求不存在的工具模型空转、编造工具名对照工具列表检查

最后一条最容易被忽视:提示词和工具集是同一个接口的两面。你删了个工具却没改 Prompt,模型就会一本正经地「调用」一个不存在的函数,然后你盯着日志怀疑人生。


🌙 九、写在最后

本节解决:把前面八节压缩成三句话,方便你带走。

做完这个项目,有三句话我比较确定:

  1. Agentic 开发的核心不是 Prompt,是状态机。 Prompt 决定「说什么」,状态决定「记什么、去哪、能不能回来」。路由错了,Prompt 写得再花也白搭。
  2. 检索应该是个工具,不是一段流程。 什么时候查、查几次,交给模型判断,比在代码里写死 if 灵活得多。
  3. 传统后端的基本功一个都没浪费。 依赖注入、连接池、事务边界、异常分层、日志上下文——AI 应用不是新物种,它只是多了一个「不确定的调用」。

最后附一张对照表,方便你把自己的项目往上套:

步骤比喻代码对象
① 接单服务员POST /api/v1/chat · ChatService
② 认桌号桌号thread_id = chat_threads.id · query_owned()
③ 分单分单员route_node · Command(goto)
④ 下灶取料灶台 + 仓库子图 · @tool · BM25BuiltInFunction
⑤ 端菜一道一道上astream_events · done
⑥ 落账本桌号小本子AsyncPostgresSaver

🌙 最后一句:大模型负责让产品有想象力,状态机负责让你别被这份想象力弄死。

说句实在话,这个项目里最花时间的不是调模型,而是调那条「流程走不通」的路:状态对不上、字段被投影丢掉、事件类型猜错。模型反而是最好相处的那个——它不懂就问你要,流程不会。


📚 参考资料

如果你也在做类似的项目,欢迎在评论区说说你踩的是哪一个坑🧐。