把简历工具做成 AI Agent这件事的曲折程度超出我预期。最初我只是想做一个自动润色简历的小工具用户把简历丢进来AI 帮忙改一改。可等需求拆完才发现真正能用的简历助手压根不是调一次 LLM 接口那么简单——它得读懂岗位 JD从用户零散的经历里提炼亮点判断现有简历哪里写得不到位给出修改方案用户不满意还得继续对话迭代。这里面有推理循环、有状态记忆、有人工介入典型的 Agent 场景。我最终落地的方案是前端和 API 层全部用 Next.js 承载Agent 的编排交给 LangGraph.js模型走 OpenAI 兼容接口。项目上线一个多月实测能扛住日常几百的并发量单次对话的 token 消耗也压在了可控范围内。这篇就把从架构选型、状态图设计、流式响应到并发和成本控制的完整过程复盘一遍。如果你正打算用 Next.js 加 LangGraph.js 做 AI Agent或者做的项目同样需要多步推理 断点交互这种复杂流程这篇应该能帮你少踩几个坑。1. 需求与架构为什么这个场景值得用 Agent1.1 简历工具为什么需要 Agent而不是普通表单先说业务痛点。传统做法是做一个表单用户填完基本信息后端拼一个 prompt 丢给大模型返回一篇看起来很厉害的简历。这种方案不是不能用但体验和效果都很拉胯AI 不知道目标岗位到底要什么不知道用户经历里哪些才是面试官关心的改出来的简历全是套话用户看完只会觉得这写了等于没写。真实场景比这复杂得多。用户说我做过三年电商运营帮我写简历Agent 要做的不是一次性输出而是先拆解岗位 JD提取硬性要求和关键词再抽取用户经历里的工作内容、项目成果、量化数据接着判断哪些经历跟目标岗位匹配哪些描述太弱需要重写然后按照 STAR 法则逐节改写最后还要校验格式是否规范、事实是否被保留然后停下来让用户确认。这里面的核心特征是多步骤、有循环校验不过就回去改、有分支用户不满意继续调满意就结束、需要上下文记忆。普通表单根本承载不了这种对话式的工作流。我后来复盘时跟团队说这个产品如果不是做成 Agent就等于让用户自己在一个万能输入框里跟一个失忆的大模型反复描述需求迟早劝退。所以链路虽然长了但业务价值很明确用户能在一个对话里完成诊断—改写—确认—导出的完整闭环。这种深度交互带来的转化率是普通表单完全比不了的。1.2 技术选型Next.js 全栈加 LangGraph.js不整微服务的理由选型阶段其实犹豫过要不要用 Python 系毕竟 LangGraph 的 Python 版本生态更成熟、资料更多。但对比之后我还是选了 TypeScript 一条链路。第一是部署成本。个人开发者或者小团队做一个 AI 产品最怕的就是拆出三四个服务前端一个 Node后端一个 Python中间还要做联调和鉴权。用 Next.js 全栈前端页面、Route Handler、文件上传、导出服务全在一个应用里本地开发一套代码跑到底部署也就是一个应用的事。第二个原因是语言心智负担。前端同学能直接上手写 API 层不需要跨语言切换LangGraph.js 虽然资料少一点但 API 设计和 Python 版本一脉相承核心概念看图、状态、节点就能迁移。再就是在 LangGraph.js、LangChain.js 和自研状态机之间怎么选。我一开始天真地想简历流程也就是分析、改写、生成用 LangChain 链式调用串起来不就行了后来发现完全不是。链式调用的本质是前一个输出接后一个输入一旦流程里出现校验失败要跳回去重写用户中途反馈要改变路径这类分支代码就会变成一团乱麻。自研状态机呢倒是不依赖框架但状态存储、断点恢复、流式输出全都得自己造轮子工作量瞬间就上去了。LangGraph.js 解决的核心问题正是这个用图来描述流程节点负责具体业务边决定流转方向内置状态管理和断点恢复。相当于把 Agent 的骨架框架化了业务代码只写在节点里维护起来非常舒服。1.3 整体架构与数据流整个服务的结构可以分成四层浏览器端是 Next.js 页面和组件API 层是 App Router 的 Route HandlerAgent 编排层是 LangGraph.js 的 StateGraph 实例数据层是 Postgres 存会话检查点和业务数据对象存储放简历文件和导出结果。浏览器发起请求后先是进入/api/agent这个端点带着用户当前的消息和 threadId。Next.js 的 Route Handler 把请求转给 LangGraph.js 运行时Agent 按图执行过程中调用大模型、读写 Postgres 检查点产生的结果通过 SSE 流式推回前端。前端收到后一边展示节点状态正在分析岗位要求…正在改写项目经历…一边把最终草稿渲染成可视化版本。浏览器 ↓ 对话 / 上传 / 导出 Next.js (App Router) ├─ / 聊天与简历编辑页面 ├─ /api/agent SSE 流式 Agent 入口 ├─ /api/export 导出 Word/PDF └─ /api/files 简历上传与解析 ↓ LangGraph.js 图运行时 (StateGraph Checkpointer) ↓ LLM ProviderOpenAI 兼容接口为什么第一版不拆微服务因为单体应用完全够用。拆服务只会引入额外的网络开销、部署复杂度和排障成本对 MVP 阶段没有好处。等并发真正上来了Next.js 这一层可以横向扩容LangGraph 的检查点存在 Postgres 里天然支持多实例共享状态到时候再按需拆分也来得及。2. LangGraph.js 工作流把简历 Agent 拆成一张图2.1 状态设计Agent 记忆的载体LangGraph.js 里最核心的概念是状态State。一开始我以为状态就是一个 messages 数组后来被现实教育了多个节点同时往状态里写东西如果只是简单赋值后写的会把先写的整个覆盖掉。比如rewriteNode刚更新完简历草稿validateNode又想记录校验结果彼此之间不协调最终状态就乱了。LangGraph 的解法是给每个字段配 reducer。每个节点返回的不是完整状态而是增量由 reducer 决定怎么合并。这是整个框架最值得理解的部分。我的状态定义大致长这样import { Annotation } from langchain/langgraph; export const AgentState Annotation.Root({ messages: AnnotationChatMessage[]({ reducer: (current, incoming) trimMessages([...current, ...incoming]), }), profile: AnnotationUserProfile | null({ reducer: (_, incoming) incoming ?? _, }), resumeDraft: AnnotationResumeSection[] | null({ reducer: (_, incoming) incoming ?? _, }), jobAnalysis: AnnotationJobAnalysis | null({ reducer: (_, incoming) incoming ?? _, }), feedback: AnnotationValidationFeedback | null({ reducer: (_, incoming) incoming ?? _, }), });几个字段的设计思路简单说一下。messages是所有对话消息reducer 是追加合并但我加了一个trimMessages做裁剪只保留最近几轮防止上下文无限膨胀。profile是用户简历结构化之后的数据采用新值非空才覆盖的策略这样即便某个节点没处理 profile它也不会被意外清空。resumeDraft存当前简历草稿的分节结构这是改写节点的核心工作对象。jobAnalysis存 JD 解析结果feedback存循环校验的反馈这两个字段驱动后面的条件边。当时踩过的一个坑把简历全文直接塞进 messages 当普通消息存结果几轮对话之后 token 消耗直线上升而且 LLM 很容易把对话消息和简历内容弄混。后来改成独立字段单独存储对话里只保留摘要和引用问题立刻缓解。状态设计的原则就是把需要长期记忆的结构化数据跟对话流分开别什么都在 messages 里挤。2.2 节点与条件边诊断-建议-改写-校验的循环图的主体由节点和边组成。每个节点是一个 async 函数接收当前状态返回增量边决定执行顺序。我的简历 Agent 拆出了六个核心节点节点职责主要输入主要输出analyzeJobNode解析岗位 JD提取关键词、硬性要求、偏好岗位描述jobAnalysisextractProfileNode抽取用户经历按教育/工作/项目/技能分节原始简历文本profilegapAnalysisNode对比现有简历和岗位要求找出差距profile jobAnalysisgapListrewriteSectionNode按照差距逐节改写简历resumeDraft gapList新版 resumeDraftvalidateNode校验格式、事实保留、语气给出反馈resumeDraftfeedback isPassrouterNode条件路由决定继续改写还是结束feedbackrewrite 或 end构建图的代码并不复杂最重要的是条件边的配置。我简化一下import { StateGraph, START, END } from langchain/langgraph; const workflow new StateGraph(AgentState) .addNode(analyzeJob, analyzeJobNode) .addNode(extractProfile, extractProfileNode) .addNode(gapAnalysis, gapAnalysisNode) .addNode(rewrite, rewriteSectionNode) .addNode(validate, validateNode) .addEdge(START, analyzeJob) .addEdge(analyzeJob, extractProfile) .addEdge(extractProfile, gapAnalysis) .addEdge(gapAnalysis, rewrite) .addEdge(rewrite, validate) .addConditionalEdges(validate, routerNode, { rewrite: rewrite, end: END, }) .compile({ checkpointer });routerNode 的逻辑就是读取上次校验的反馈判断是否还有必须修的硬伤、是否超过重试次数。如果没过就回到 rewrite如果过了就走 END。这里有个容易被忽略的细节条件边映射表里必须覆盖全部分支否则运行时直接抛错。我当时漏了一个分支结果线上偶发报错查了半天才发现是模型返回的状态不在映射表里。后来我在 routerNode 里强制加了一个兜底逻辑任何未知状态一律走 END宁可不完美也不能让流程卡死。循环次数也要控制。LangGraph 默认 recursionLimit 是 25简历改两三次就够了无限循环只会烧 token。我在配置里显式把 recursionLimit 降到 20并在 validateNode 里计数超过两次重试就直接返回当前版本已可用建议直接导出。2.3 interrupt 断点与人工介入Agent 落地最容易忽略的能力做 Agent 产品最容易被忽略的是人在环里。AI 改完简历直接输出用户没有任何确认和干涉的机会体验是很可怕的——万一 AI 把用户的真实经历改得面目全非用户根本来不及阻止。LangGraph 的interrupt机制正好解决这个问题图执行到某个节点时可以暂停等待用户输入再恢复执行。我在确认版本这个环节用了 interrupt。代码大概是这样的import { interrupt } from langchain/langgraph; async function confirmNode(state: AgentState) { const feedback interrupt({ type: confirm_draft, draft: state.resumeDraft, }); return { messages: [ ...state.messages, { role: user, content: 用户反馈${feedback.comment} }, ], }; }前端通过agent.stream()拿到__interrupt__事件后可以渲染一个确认/修改意见的卡片。用户点了确认就调用Command(resume: { approved: true })恢复执行用户输入修改意见就 resume 那段意见文本让图继续走 rewrite 节点。一开始我觉得这个机制可有可无加了之后用户反馈完全不一样——有确认环节用户会觉得 AI 是助手而不是自动机器信任感强了很多。2.4 对比链式调用同样是写简历代码差别在哪有人可能觉得我用 LangChain 的链式调用也能拼出这个流程为什么非得上图拿用户中途改需求这个场景对比一下就明白了。链式调用的写法是prompt1 分析 JD 得到结果拼进 prompt2 抽取经历再拼进 prompt3 生成简历。当用户说第二段再口语化一点你得自己找到第二段对应哪个变量然后手动拼一个新 prompt把前面几步的结果重新塞进去重新跑一遍——每次需求变化代码都要跟着改结构。LangGraph 则完全不需要。rewrite 节点天然持有当前 resumeDraft用户反馈通过 feedback 字段传进来条件边把流程重新引到 rewrite 节点节点内部根据 feedback 调整改写指令。加一种新的人机交互方式不需要改动整个流程只加一个节点或者一条边就行。这就是图结构对链式结构的核心优势流程的分支和循环是显式建模的不是藏在 if/else 里的。当然不是所有场景都需要 LangGraph。如果只是一份 prompt 加一次调用杀鸡不必用牛刀。但凡是有循环、有分支、需要断点恢复和状态持久化的 Agent花点时间把图画出来比手工硬写省一半代码后续维护也清爽得多。3. Next.js 实操前端交互、API 层与流式响应3.1 路由与 API 端点设计Next.js 承载的功能主要是四个端点聊天入口、导出、文件上传、页面本身。用 App Router 的 Route Handler 实现跟前端代码同仓库不用维护两个服务。端点方法职责/GET聊天与简历编辑主页面/api/agentPOST接收用户消息与 threadIdSSE 返回 Agent 节点更新/api/exportPOST接收 resumeDraft导出 docx / pdf/api/filesPOST接收简历文件解析后返回结构化 profile为什么用 POST 加 SSE 而不是 WebSocket因为简历对话场景是一问一答模型单次响应时长也就十几秒Post/SSE 模式完全够用。而且 SSE 基于普通 HTTP任何负载均衡器都能透传不需要维护长连接网关扩展性方面省事很多。WebSocket 适合服务端频繁主动推送的场景这里用不上。3.2 核心用 ReadableStream 实现流式 SSE前端体验的关键是打字机效果不能等模型全部生成完才一次性返回。LangGraph 的stream()天然支持流式输出配合 Next.js 的 ReadableStream 可以很轻松地把更新推给前端。// app/api/agent/route.ts import { NextRequest } from next/server; export async function POST(req: NextRequest) { const { threadId, message, resumeText } await req.json(); const encoder new TextEncoder(); const stream new ReadableStream({ async start(controller) { try { const agent getAgent(); // 全局单例避免每次请求重复编译图 const config { threadId, recursionLimit: 20, streamMode: updates, }; const input { messages: [{ role: user, content: message }], resumeText, }; const updates await agent.stream(input, config); for await (const update of updates) { const payload JSON.stringify(update); controller.enqueue(encoder.encode(data: ${payload}\n\n)); } } catch (err) { const payload JSON.stringify({ error: (err as Error).message }); controller.enqueue(encoder.encode(data: ${payload}\n\n)); } finally { controller.close(); } }, cancel() { // 客户端断开时在这里做清理避免资源泄漏 }, }); return new Response(stream, { headers: { Content-Type: text/event-stream }, }); }这里的streamMode: updates很关键它只返回每个节点更新的字段而不是把整个状态全量推给前端减少了大量冗余传输。前端解析事件的时候可以根据事件内容渲染不同的 UI 提示比如节点名称是 gapAnalysis 就显示正在比对岗位差距。3.3 前端聊天界面与 useChat聊天界面我用了 Vercel AI SDK 的useChat来管理消息状态它可以原生处理 SSE 流式返回省掉自己维护正在输入状态的麻烦。不过 AI SDK 默认约定是/api/chat端点我这边接口是自定义的/api/agent所以对接时做了一层适配把消息数组转成 Agent 要求的格式。有个细节值得提threadId 要持久化到 localStorage这样用户刷新页面后还能继续上次的对话。如果每次打开都新建 threadIdLangGraph 那边的会话历史就用不上了用户还得重新贴一遍简历体验大打折扣。版本对比卡片是前端的一个亮点。我做了双栏展示左边是用户原稿右边是 AI 改稿相同的段落用相同颜色块标记改动的句子高亮并标注修改原因。这个功能其实不复杂关键是节点输出结构要规范——我要求 rewrite 节点必须返回{ originalText, rewrittenText, reason }这种结构方便前端渲染。这也是 Agent 设计时就要兼顾产品需求的典型例子不能光想着模型输出还得想好前端怎么消费。3.4 简历上传与解析怎么把一份杂乱的简历变成结构化数据简历上传解析是个容易被低估的环节。网上用户的简历千奇百怪PDF、Word、扫描件都有甚至还有人直接粘贴网页排版。这块我做了一个上传端点走的是文档解析加二次结构化的流程.docx文件用 mammoth 转成 HTML再清洗成纯文本.pdf文件用 pdf-parse 抽取文本但中文字体处理是个老大难经常抽出来是乱码需要额外配置字体映射图片型 PDF就是扫描件pdf-parse 抽不出文本得接 OCR 服务兜底抽出来的纯文本再交给 LLM 做一次结构化按教育背景、工作经历、项目经历、技能标签分节输出成 profile 字段。文件大小限制在 5MB 以内服务端做类型校验防止恶意上传。这个流程里最花时间的其实是清洗到结构化这一步。真实简历很多是两栏排版、表格结构直接抽文本顺序全乱LLM 二次结构化能救回来一部分但也需要你在 prompt 里写清楚请忽略页眉页脚按时间倒序输出经历。OCR 我最后直接接的云服务本地部署 OCR 在并发上来之后太吃资源性价比不高。4. 并发与生产化AI Agent 怎么扛住真实流量4.1 第一个坑用 MemorySaver 直接上线内存爆了本地开发的时候LangGraph 默认用 MemorySaver 存状态所有会话的 checkpointer 都放在进程内存里。当时没多想直接复用到了生产。结果上线第一个星期还好后面并发一上来就出问题几十个会话同时跑内存持续上涨偶尔还会请求超时更离谱的是进程一重启所有用户的会话状态全丢。后来才反应过来MemorySaver 是单机开发用的玩具根本不是生产方案。状态必须持久化到数据库让所有实例共享才能水平扩展。我换成了 PostgresSaverimport { PostgresSaver } from langchain/langgraph-checkpoint-postgres; const checkpointer PostgresSaver.fromConnString(process.env.DATABASE_URL!); const agent workflow.compile({ checkpointer });第一次连接时会自动建表不用手动初始化。需要注意连接池配置默认连接数在并发高的时候会成为瓶颈我把 max 调到了 20并且跟业务表共用一个数据库初期省了一台实例。换上之后内存占用降了下来状态不再丢多实例部署也顺理成章了。4.2 无状态入口与限流、超时Next.js 的 Route Handler 很适合做无状态入口每个请求只负责把用户消息交给 Agent 并转发输出不保存任何本地状态。这样 API 层可以随意横向扩容真正的会话状态都在 Postgres 里每个实例都能读到。但无状态不等于无限流。模型供应商的 API 是有并发配额和速率限制的不控制的话一旦流量峰值到来到处都是 429 和超时。我加了两层防护。第一层是用户维度限流用 Upstash Rate Limitimport { Ratelimit } from upstash/ratelimit; import { Redis } from upstash/redis; const ratelimit new Ratelimit({ redis: Redis.fromEnv(), limiter: Ratelimit.slidingWindow(20, 60 s), }); export async function POST(req: NextRequest) { const ip req.headers.get(x-forwarded-for) ?? unknown; const { success } await ratelimit.limit(ip); if (!success) { return Response.json({ error: 请求过于频繁请稍后再试 }, { status: 429 }); } // ... }第二层是单请求超时。Agent 执行链路有时候会因为模型响应慢而拖很久用户等不住。我用 Promise.race 给整个流式响应套了一个 30 秒的超时兜底超时就返回AI 思考时间过长请重试避免用户无限白等。模型调用本身也加了指数退避重试遇到 rate limit 或瞬时 5xx 会自动重试一到两次。4.3 模型策略与 token 成本控制模型选型直接影响成本和体验这块我调了好几轮。规律是重活岗位差距分析、简历改写必须上旗舰模型质量和稳定性都好轻活经历抽取、格式校验用小模型就够又便宜又快。我后来把大部分理解类任务切到 mini 级别模型综合成本降了六成左右用户体感几乎没有差异。token 成本控制有几个实操手段。第一是 System Prompt 精简我一开始堆了一大段你是一名资深 HR 和简历顾问……足有 1200 个 token后来压到 350 token只保留核心规则效果差别不大。第二是历史消息裁剪保留最近 4 轮对话加上简历结构摘要而不是把全部原文塞进上下文。第三是工具结果截断有些节点会把整段简历文本放回上下文供模型参考其实大部分是浪费改成只放摘要和关键指标就行。成本这块要前置考虑别等账单出来再优化那就已经亏了一波了。4.4 可观测性与成本看板Agent 跑久了你会发现它就是个黑盒你不知道用户卡在哪个节点、哪个模型响应慢、哪个步骤消耗的 token 多。所以日志一定要从一开始就埋好。我在每次agent.stream()之后把一次完整的执行记录写进日志表{ threadId: xxx, nodes: [analyzeJob, extractProfile, gapAnalysis], model: claude-sonnet-4, inputTokens: 8200, outputTokens: 1500, durationMs: 12400, success: true, }这些数据能回答三个关键问题用户是不是都在某个节点失败哪个节点最耗时单个会话的 token 消耗是多少。定期跑一个 SQL 按天聚合就能看到成本走势也能反过来指导 prompt 优化。我在排查慢响应问题时就是靠日志定位到 gapAnalysis 节点因为 prompt 不明确导致模型反复思考改完 prompt 之后耗时降了一半。5. 常见问题与排查实录5.1 问题排查速查表上线一个月我整理了一份高频问题速查表基本覆盖了 Next.js 加 LangGraph.js 方案的大部分坑现象可能原因解决办法图执行到一半卡住不返回条件边没有覆盖全部分支或模型状态值不在映射表里条件边加 END 兜底给模型输出做枚举校验报 RecursionError 或者执行次数过多循环节点缺少终止条件显式配置 recursionLimit节点内加重试计数模型输出 JSON 解析失败模型返回的 JSON 不合法或夹杂了 markdown 代码块改用 function calling 或 JSON mode用 Zod schema 校验用户看到一半断线了服务端超时、代理断连服务端流式写入完整响应前端支持断线重连后拉取缓存结果中文简历解析出来是乱码pdf-parse 字体问题或扫描件配置字体映射图片 PDF 走 OCR 服务多实例部署后状态错乱checkpointer 没持久化或 threadId 不一致换 PostgresSaver前端持久化 threadIdtoken 消耗暴涨messages 无限增长或工具结果全量回填加消息裁剪策略工具结果只返回摘要5.2 一次线上事故条件边分支没写全有一次线上偶发报错用户反馈AI 突然不回话了日志里看到Error: Invalid update returned by node routerNode。查了半天原因是模型在 validateNode 输出的反馈里某个字段值不在我预设的分支映射表内routerNode 返回了一个未定义的状态LangGraph 直接抛错终止了整个流。这个问题的根源是模型输出天然不可控。即使 prompt 写死了只允许返回 rewrite 或 end模型偶尔还是会给出意外值。修复方案是两层第一层在 routerNode 里对模型输出做枚举校验不在白名单里的值一律强制转为 end第二层在条件边映射表里加一个_else兜底分支指向 END保证任何情况都不会卡死。自此之后再没出现过这类中断。5.3 上下文爆炸的教训别把整份简历重复塞进对话还有一次是网上一顿吐槽运行几轮之后响应越来越慢token 消耗高得吓人。我翻日志发现rewrite 节点为了让模型记住简历全文把整份结构化简历原样放进了消息上下文而且每一轮循环都重复放一遍。对话超过五轮之后上下文里塞了五份完整简历token 直接爆炸。修复方式是改成了摘要引用加局部窗口上下文里只保留简历结构摘要、当前正在改写的分节内容、以及最近的用户反馈不再全量塞原文。这样既保证模型有足够的上下文感知又把 token 消耗压到一个稳定水位。Agent 的记忆管理真的不是把东西存下来就完了存什么、何时引用、何时丢弃这些细节直接决定成本和稳定性。6. 落地后的体会与扩展方向6.1 几点真实体会做这个项目最大的感悟Agent 真正难的不是模型调用而是状态和流程控制。模型能力再强流程设计一团乱产品照样不好用。Graph 的方式逼着你把诊断、改写、校验、确认这些步骤显式画出来每一步的输入输出都清清楚楚这才是它最大的价值。还有一个感受是人工介入不是退步。interrupt 机制加上之后用户反而觉得产品更智能、更可信了。Agent 产品要的是人机协同不是全自动黑盒。用户有确认权有修改权这个产品才立得住。成本控制一定要前置。我第一次看到账单的时候是有点肉疼的。后来把轻任务切小模型、上下文做裁剪、工具结果做摘要整体成本才算稳定下来。这些东西应该在架构设计阶段就想好而不是上线后亡羊补牢。6.2 后续扩展从简历工具到通用 Agent 底座这个项目的架构稍微抽象一下其实可以复用到很多场景岗位匹配、文档助手、面试模拟、内容审核……都是多步推理 人工介入 状态持久化的模式。我后续打算把几个通用能力抽出来一个可配置的状态图框架一套 Postgres 检查点基础设施一组模型路由和限流策略。把这些沉淀成内部脚手架之后再开新项目就不用重复造轮子了。最后分享一个个人经验如果让我重新做一次第一件事不是写业务节点而是先把 checkpointer 和 interrupt 跑通。这两个点定了后面往图里加节点只是体力活反过来的话业务代码写了一大堆回头再补状态持久化和人工介入改动成本会高到让你怀疑人生。Agent 项目的骨架永远比血肉重要。