大模型 Agent 构建平台开发：LLM + 向量库 + NextJS 前端实战

大模型 Agent 构建平台开发LLM 向量库 NextJS 前端实战一、为什么要在 NextJS 上构建 Agent 平台2026 年大模型 Agent 已经从技术演示走向生产落地。但一个值得深思的现象是大量 Agent 项目在原型阶段表现惊艳一旦进入生产环境就暴露出状态丢失、工具调用不可控、前端体验割裂等问题。根源往往不在模型能力本身而在于工程架构的缺失。传统方案通常采用“前端框架 独立后端服务”的分离架构。以 Next.js FastAPI 为例前端负责 UI 渲染后端负责 Agent 编排和向量检索。这种架构在团队分工上清晰但引入了额外的网络跳转、部署复杂度和状态同步成本。对于中小规模 Agent 平台而言这种分离带来的收益往往不足以抵消其复杂性。Next.js App Router 的出现改变了这一局面。它允许在同一项目中定义 API Route Handler 和 React Server ComponentAgent 的推理逻辑、工具执行和流式响应可以完全运行在 Next.js 的运行时中无需独立后端进程。LangChain 官方提供的 Next.js 部署方案正是基于这一理念流式聊天 UI、子 Agent 和线程历史全部由 Next.js Route HandlersHTTP SSE实现“No separate backend process”。这意味着一个全栈开发者可以在单一代码库中完成从向量检索、Agent 编排到前端交互的全部工作。本文将基于 LLM 向量库 NextJS 的技术栈完整拆解 Agent 构建平台的工程实现。二、整体架构三层解耦的 Agent 平台在动手写代码之前先明确平台的架构分层。推荐采用“三横一纵”的设计横向三层Agent 编排层负责 LLM 推理决策、工具调用调度、多轮对话状态管理。核心是 LangGraph 的 StateGraph 或 Vercel AI SDK 的 ToolLoopAgent知识检索层负责文档向量化、相似度检索、上下文注入。向量库选型和 RAG 流水线在此层实现交互层Next.js App Router 负责页面路由和 API Route HandlerReact 负责流式 UI 渲染和用户交互。纵向贯穿会话状态管理。Agent 平台与普通 Chatbot 的本质区别在于它需要维护跨轮次的结构化状态——不仅包括对话历史还包括中间执行步骤、工具调用结果和待确认的 slot 信息。某生产级 Agent 项目的状态定义可以作为一个参考范式状态中需要包含用户当前输入、对话历史符合 OpenAI 消息格式、执行轨迹action_type, action_name, result 的元组列表、最终输出、重试计数和当前步骤编号。这种显式状态管理是 Agent 可靠性的基石。三、技术栈选型为什么是这一套3.1 LLM 接入层Vercel AI SDKVercel AI SDK 是当前 Next.js 生态中最成熟的 LLM 接入方案。它提供了三个核心函数generateText用于一次性文本生成streamText用于流式响应generateObject配合 Zod schema 用于结构化输出。更关键的是AI SDK 通过 AI Gateway 实现了多模型统一接入。开发者只需传入creator/model-name格式的模型字符串Gateway 自动解析提供商、完成认证和路由。应用代码不需要因为从 GPT 切换到 Claude 或 Gemini 而改动。在 Agent 场景中streamText是使用频率最高的函数。它支持tools参数用于工具调用配合maxSteps可以自动完成多步推理循环。3.2 Agent 编排层LangGraph.js vs Vercel AI SDK AgentLangGraph.js 提供了基于状态图的显式控制流将 Agent 推理过程建模为有向图每个节点代表一个计算步骤如调用 LLM、执行工具每条边定义状态流转条件。这种设计的优势在于控制流的透明性——开发者可以精确知道每个状态节点的输入输出便于调试和性能优化。Vercel AI SDK 的ToolLoopAgent则更加轻量。它封装了语言模型和工具集运行自主推理循环调用工具、将结果反馈给模型直到获得完整答案。适合工具数量有限、流程相对简单的场景。选型建议如果 Agent 需要条件分支、并行执行、循环重试等复杂控制模式选择 LangGraph.js如果是标准的工具调用型 AgentVercel AI SDK 的 ToolLoopAgent 更简洁高效。3.3 向量库选型pgvector 是大多数场景的最优解2026 年向量库选型的核心结论很明确如果已经在使用 PostgreSQLpgvector 是最务实的选择。它通过 Postgres 扩展添加向量数据类型和相似度搜索操作符向量嵌入与关系数据共处同一数据库可以执行跨系统的 JOIN 查询。pgvector 在 v0.7 版本加入 HNSW 索引后性能已经可以与独立向量数据库竞争。默认 HNSW 配置即可达到 95% 的召回率。对于 RAG 场景pgvector 通过 Prisma 或 Drizzle 集成后在 1000 万向量规模以下完全够用。其他选项的适用场景Qdrant 适合需要自托管且对 ANN 搜索速度有极致要求的场景支持亚毫秒级查询Pinecone 适合追求零基础设施、快速上线的团队。如果使用 Supabase其内置的 pgvector 是 Next.js 项目的自然选择——不需要新增服务且可以将向量检索与用户数据通过标准 SQL JOIN 关联。四、核心实现一Agent 推理循环与工具调用4.1 定义工具集工具是 Agent 的“手脚”。在 Vercel AI SDK 中工具通过 Zod schema 定义参数结构SDK 自动将其转换为 LLM 可理解的 JSON Schema。// lib/agent/tools.tsimport{tool}fromai;import{z}fromzod;import{searchDocuments}from/lib/rag/search;import{queryDatabase}from/lib/db;exportconstagentTools{search_knowledge_base:tool({description:在知识库中检索相关文档片段。当用户询问需要事实依据的问题时使用。,parameters:z.object({query:z.string().describe(检索关键词或语义查询),topK:z.number().default(5).describe(返回的文档片段数量),}),execute:async({query,topK}){constresultsawaitsearchDocuments(query,topK);returnresults.map(r({content:r.content,source:r.source,score:r.score,}));},}),query_structured_data:tool({description:查询结构化数据库。当用户询问统计数据、列表或需要精确数值时使用。,parameters:z.object({sql:z.string().describe(SQL 查询语句),}),execute:async({sql}){returnawaitqueryDatabase(sql);},}),};工具描述的质量直接影响 Agent 的决策准确性。描述应该清晰说明“什么时候用这个工具”而不仅仅是“这个工具做什么”。4.2 构建推理循环在 API Route Handler 中使用streamText配合工具集和maxSteps启动 Agent 循环// app/api/chat/route.tsimport{streamText}fromai;import{agentTools}from/lib/agent/tools;exportconstruntimenodejs;exportconstdynamicforce-dynamic;exportasyncfunctionPOST(req:Request){const{messages,threadId}awaitreq.json();constresultstreamText({model:openai/gpt-4o,system:你是一个企业知识助手。回答问题时优先使用 search_knowledge_base 工具检索知识库。 如果检索结果不足以回答明确告知用户不要编造信息。,messages,tools:agentTools,maxSteps:5,});returnresult.toDataStreamResponse();}maxSteps: 5限制了 Agent 的最大推理步数防止无限循环。runtime nodejs确保 Route Handler 运行在 Node.js 运行时而非 Edge Runtime因为向量库的数据库连接通常不支持 Edge。4.3 使用 LangGraph 实现复杂控制流当 Agent 需要条件分支和循环重试时LangGraph 的状态图模型更合适。以下是一个带工具执行节点的循环图// lib/agent/graph.tsimport{StateGraph,END}fromlangchain/langgraph;import{ChatOpenAI}fromlangchain/openai;import{ToolExecutor}fromlangchain/langgraph/prebuilt;interfaceAgentState{messages:BaseMessage[];intermediateSteps:Array[string,string,any];finalOutput?:string;retryCount:number;}constgraphnewStateGraphAgentState({channels:{messages:{value:(a,b)a.concat(b)},intermediateSteps:{value:(a,b)a.concat(b)},retryCount:{value:(a,b)b??a},},}).addNode(agent,agentNode)// LLM 推理节点.addNode(tools,toolNode)// 工具执行节点.addEdge(__start__,agent).addConditionalEdges(agent,shouldContinue,{tools:tools,[END]:END,}).addEdge(tools,agent);// 工具执行后回到推理exportconstagentGraphgraph.compile();这种图结构的核心价值在于每一次“思考-行动-观察”循环都是显式的状态转换可以精确追踪 Agent 在每一步做了什么决策、基于什么信息。五、核心实现二向量库集成与 RAG 检索5.1 文档向量化流水线文档从上传到可检索需要经历分块、嵌入、存储三个阶段。在 Next.js 中这一过程通过 Server Action 或 Route Handler 异步执行// lib/rag/ingest.tsimport{OpenAIEmbeddings}fromlangchain/openai;import{RecursiveCharacterTextSplitter}fromlangchain/text_splitter;import{prisma}from/lib/db;constembeddingsnewOpenAIEmbeddings({model:text-embedding-3-small});exportasyncfunctioningestDocument(content:string,metadata:{source:string;tenantId:string}){constsplitternewRecursiveCharacterTextSplitter({chunkSize:800,chunkOverlap:200,});constchunksawaitsplitter.createDocuments([content]);for(constchunkofchunks){constvectorawaitembeddings.embedQuery(chunk.pageContent);awaitprisma.$executeRawINSERT INTO document_chunks (content, embedding, source, tenant_id) VALUES (${chunk.pageContent},${vector}::vector,${metadata.source},${metadata.tenantId});}}5.2 RAG 检索工具检索工具是 Agent 工具集中最核心的一个。它需要处理查询嵌入、向量相似度搜索和结果格式化// lib/rag/search.tsimport{OpenAIEmbeddings}fromlangchain/openai;import{prisma}from/lib/db;constembeddingsnewOpenAIEmbeddings({model:text-embedding-3-small});exportasyncfunctionsearchDocuments(query:string,topK:number,tenantId:string){constqueryVectorawaitembeddings.embedQuery(query);constresultsawaitprisma.$queryRawSELECT content, source, 1 - (embedding ${queryVector}::vector) AS score FROM document_chunks WHERE tenant_id ${tenantId}ORDER BY embedding ${queryVector}::vector LIMIT${topK};returnresults.filter(rr.score0.7);}注意WHERE tenant_id ${tenantId}这个条件——多租户隔离必须嵌入检索层而非在生成后过滤。这确保 Agent 的推理过程中不会“看到”不属于当前用户的内容。5.3 上下文注入策略检索到的文档片段需要以合适的方式注入 LLM 上下文。推荐的做法是将检索结果作为工具返回的消息而非直接拼接到 System Prompt 中。这样做的好处是 Agent 可以自主决定何时检索、检索什么而不是每轮对话都强制注入// 工具返回的结果会自动以 tool result 消息的形式进入对话历史// LLM 在下一步推理中会看到这些结果并据此生成回答// 不需要手动拼接 Prompt六、核心实现三流式交互与前端渲染6.1 使用 useChat Hook 管理流式状态Vercel AI SDK 的useChatHook 是前端流式交互的核心。它自动管理与 API Route 的流式连接、消息状态和输入处理// app/chat/page.tsx use client; import { useChat } from ai/react; export default function ChatPage() { const { messages, input, handleInputChange, handleSubmit, isLoading } useChat({ api: /api/chat, onToolCall: ({ toolCall }) { console.log(Agent 正在调用工具:, toolCall.toolName); }, }); return ( div classNameflex flex-col h-screen max-w-3xl mx-auto p-4 div classNameflex-1 overflow-y-auto space-y-4 {messages.map(m ( div key{m.id} className{m.role user ? text-right : text-left} div className{inline-block p-3 rounded-lg ${ m.role user ? bg-blue-500 text-white : bg-gray-100 }} {m.content} /div /div ))} {isLoading div classNametext-gray-400Agent 思考中.../div} /div form onSubmit{handleSubmit} classNamemt-4 flex gap-2 input value{input} onChange{handleInputChange} classNameflex-1 border rounded-lg px-4 py-2 placeholder输入你的问题... / button typesubmit classNamebg-blue-500 text-white px-6 py-2 rounded-lg 发送 /button /form /div ); }onToolCall回调让前端可以感知 Agent 正在执行什么工具——这在构建 Agent 平台时尤其重要用户需要看到 Agent 的“工作过程”而不仅仅是最终答案。6.2 展示 Agent 的工具调用过程Agent 平台与普通 Chatbot 的 UI 差异在于需要展示中间的推理过程。Vercel AI SDK 的useChat会自动在消息中包含工具调用信息前端可以据此渲染一个执行时间线// 在消息渲染中增加工具调用展示 {m.toolInvocations?.map((invocation, i) ( div key{i} classNametext-sm text-gray-500 my-1 pl-4 border-l-2 border-gray-300 {invocation.state call 正在调用 ${invocation.toolName}...} {invocation.state result ( details summary ${invocation.toolName} 返回结果/summary pre classNametext-xs mt-1{JSON.stringify(invocation.result, null, 2)}/pre /details )} /div ))}6.3 流式渲染的性能优化LLM 逐 token 生成响应传统方案需要等待完整生成后才能展示。useChat通过 SSEServer-Sent Events将 token 实时推送到浏览器用户在网络往返的瞬间即可看到输出。对于 Agent 平台需要注意一个额外问题工具调用会中断流式输出。当 Agent 决定调用工具时流式响应会暂停等待工具执行完成后再继续。前端应该通过onToolCall回调展示“正在检索”等状态提示避免用户误以为系统卡死。七、状态持久化从内存到生产级7.1 开发环境的会话管理LangChain 的 Next.js 部署示例默认使用MemorySaver作为 checkpointer会话状态存储在进程内存中。这在本地开发中完全够用但在 Vercel 这样的 Serverless 环境中冷启动和多实例部署会导致会话状态丢失。7.2 生产环境的状态持久化生产环境需要替换为持久化 checkpointer。LangChain 提供了多个选项Redislangchain/langgraph-checkpoint-redis、PostgreSQLlangchain/langgraph-checkpoint-postgres和 SQLitelangchain/langgraph-checkpoint-sqlite。对于基于 pgvector 的架构PostgreSQL checkpointer 是最自然的选择——不需要引入新的存储服务// lib/agent/index.tsimport{PostgresSaver}fromlangchain/langgraph-checkpoint-postgres;import{agentGraph}from./graph;constcheckpointerPostgresSaver.fromConnString(process.env.DATABASE_URL);awaitcheckpointer.setup();exportconstagentagentGraph.compile({checkpointer});7.3 多租户隔离Agent 平台通常需要支持多个用户或团队。向量库层面的隔离通过tenant_id字段和 WHERE 条件实现会话层面的隔离则需要在线程 ID 中嵌入租户标识。LangChain 的 Agent Protocol 支持通过/api/threads/:threadId/state端点读取和恢复检查点状态每个 threadId 天然对应一个独立的会话空间。八、部署与运维8.1 Docker 容器化将 Next.js Agent 平台容器化时需要注意多阶段构建以减小镜像体积以及环境变量的正确注入FROM node:22-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM node:22-alpine AS runner WORKDIR /app COPY --frombuilder /app/.next/standalone ./ COPY --frombuilder /app/public ./public COPY --frombuilder /app/.next/static ./.next/static ENV NODE_ENVproduction ENV HOSTNAME0.0.0.0 EXPOSE 3000 CMD [node, server.js]Docker 官方提供了基于 Vercel AI SDK 的 Next.js Chatbot 模板的容器化方案其 Dockerfile 已经过生产验证。8.2 Vercel 部署的注意事项部署到 Vercel 时有两点需要特别注意。第一SSE 路由需要设置dynamic force-dynamic否则 Vercel 会尝试静态优化流式路由。第二向量库的区域选择——如果向量库部署在特定区域Next.js Functions 也应配置为同一区域以最小化检索延迟。8.3 成本控制策略Agent 平台的成本主要来自三部分LLM token 消耗、向量嵌入计算和数据库查询。工程层面的优化包括对高频重复查询增加 Redis 缓存层将简单问题路由到小模型处理以及在非实时场景使用批处理。n8n 提供的 RAG 工作流模板中包含了完整的 Redis 缓存方案——在向量检索之前先检查缓存命中则直接返回。九、总结在 Next.js 上构建 LLM Agent 平台的核心优势在于架构的简洁性Agent 编排、向量检索和前端交互可以在同一代码库中完成无需维护独立的后端服务。但这并不意味着可以忽略工程细节。状态持久化必须从开发环境的 MemorySaver 切换到生产级的 Redis 或 PostgreSQL checkpointer多租户隔离必须嵌入检索层而非生成层工具描述的质量直接决定 Agent 决策的准确性。从技术趋势看Agent 平台的工程化正在向“可观测、可恢复、可审计”的方向演进。LangChain 的 Agent Streaming Protocol 将流式事件标准化为协议层的事件序列使得前端可以精确追踪 Agent 的每一步推理。Vercel 的 Workflow SDK 则让 Agent 在崩溃和超时后能够恢复执行。这些能力正在从“加分项”变为“及格线”。对于正在构建 Agent 平台的团队建议从最小可行架构开始Next.js App Router Vercel AI SDK pgvector先跑通单 Agent 的工具调用和 RAG 检索再逐步叠加多租户、持久化和可观测性。工程化的价值不在于一次性搭建完美系统而在于让系统在真实负载下持续可靠地运行。