LangChain Agent 落地接入

前言

内置本地 Agent 对 AI 产品的必要性，我们已在上一篇完成论证！

接下来聚焦怎么做，从架构设计延伸到代码接入，给出我们的落地方案。

一、整体架构：分离五层

五层的职责如下：

• 模型调用应由服务封装成一个本地 Agent Runtime，而非交给前端直接完成。
• 工具执行统一收口后，增加后续能力无须重做前端，同时也能避免向前端暴露 API Key。
• 以 LangChain 快速起步，由 LangGraph 负责复杂编排，再根据业务扩展封装工具层

二、接入流程

Step 1：建立本地 Agent 服务

新建 ai-agent-server 以 Hono 框架向外提供 HTTP 服务的 workspace：

// apps/ai-agent-server/src/server.tsimport { Hono } from 'hono';import { serve } from '@hono/node-server';export const createAiAgentServer = async (config) => {const app = new Hono();// 健康检查app.get('/health', (c) => c.json({ status: 'ready', model: config.model }));// 问答接口（Step 2 实现）registerChatRoutes(app, config);const server = serve({ fetch: app.fetch, hostname: config.host, port: config.port });return { origin: `http://{config.host}:{server.address().port}`, close: () => ... };};

关键点：

• 服务运行在 127.0.0.1:39321，仅监听本地
• 前端 bundle 不包含 API Key，它只存放在服务端环境变量中。

Step 2：接入 LangChain createAgent

先完成普通问答，再于后续加入工具，由此实现最小 Agent 接入：

// apps/ai-agent-server/src/agent/createHomeAiQaAgent.tsimport { createAgent } from 'langchain';import { ChatOpenAI } from '@langchain/openai';export const createHomeAiQaAgent = (config) => {const model = new ChatOpenAI({apiKey: config.apiKey,model: config.model,temperature: 0.2,configuration: { baseURL: config.baseUrl },});return createAgent({model,tools: [],// 先不加工具，二期再扩展systemPrompt: '你是本地 AI 助手...',name: 'home_qa_agent',});};

SSE 流式接口：

// apps/ai-agent-server/src/routes/chat.tsexport const registerChatRoutes = (app, config) => {const agent = createHomeAiQaAgent(config);app.post('/api/agent', async (c) => {const body = await c.req.json();const stream = await agent.stream({ messages: body.messages },{ encoding: 'text/event-stream', streamMode: ['values', 'updates', 'messages'] },);return new Response(stream, {headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },});});};

Step 3：Electron 托管进程

让 Agent 服务随应用自动启动。开发态用 pnpm dev，打包态用 fork：

// electron/src/main/processManager/aiAgentProcess/index.tsexport const startAiAgentProcess = () => {if (app.isPackaged) {// 打包态：fork 打包后的 js 文件aiAgentProcess = childProcess.fork(path.join(__dirname, 'aiAgentServer.js'), []);} else {// 开发态：pnpm 启动 dev serveraiAgentProcess = childProcess.spawn('pnpm', ['--filter', 'ai-agent-server', 'dev'], { env: { ...process.env } });}};

前端通过 LinkService 获取运行时状态：

// 前端调用const runtime = await window.LinkService.request('v1/aiAgent/getRuntime');// runtime = { ready: true, status: 'ready', baseUrl: 'http://127.0.0.1:39321' }

Step 4：前端面板接入

右侧副面板使用 LangGraph SDK 的 useStream Hook：

// apps/src/features/home/components/AiQaPanel/index.tsximport { FetchStreamTransport, useStream } from '@langchain/langgraph-sdk/react';const AiQaPanel = ({ runtime }) => {const transport = useMemo(() => new FetchStreamTransport({apiUrl: `${runtime.baseUrl}/api/agent`,}), [runtime.baseUrl]);const stream = useStream({ transport });return (<section><header><h2>AI 问答h2>header>{/* 消息列表 */}<div>{stream.messages.map(renderMessage)}div>{/* 输入框 */}<input value={input} onChange={(e) => setInput(e.target.value)} /><button onClick={() => stream.submit({ messages: [{ type: 'human', content: input }] })}>发送button>section>);};

Step 5：权限审批机制

Agent 一旦能执行本地命令，就必须有权限审批。推荐三层模型：

用 LangGraph 的 interrupt() 实现审批中断：

// Agent 调用高风险工具时，interrupt 等待用户审批// 用户点击"允许"后，resume 继续执行

由前端展示审批卡片：

<ApprovalCardtitle="读取文件"reason="需要读取首页实现文件"riskLevel="low"onApprove={() => AiAgentApis.approveRequest(requestId)}onDeny={() => AiAgentApis.denyRequest(requestId)}/>

三、记忆管理：必须区分短期和长期

这是 Agent 区别于普通 Chat 的重要方面之一。

短期记忆（Thread Memory）

基于 thread_id 进行状态持久化，保存当前会话中的：

• 消息历史
• 任务计划
• 工具调用结果
• 中断点

使用 LangGraph 的 checkpointer 实现，开发阶段采用 MemorySaver，生产环境采用 PostgresSaver。

长期记忆（User Memory）

需要跨会话长期保存的内容：

• 用户偏好，包括输出风格和常用配置
• 授权偏好
• 常用操作模板

关键判断在于，并非所有内容都值得记忆。只应保存三类信息：用户明确要求记住的内容、高频重复且对后续有帮助的内容，以及权限与偏好类配置。

四、任务编排：简单 vs 复杂

Agent ReAct 循环适合直接处理普通问答、单工具调用这类简单任务。

显式编排复杂任务应采用 LangGraph StateGraph，这类任务包含多步骤、审批以及多阶段产物。任务编排层次推荐如下：

五、并发与错误处理

错误分类

重试原则

• 重试必须以幂等为前提：产生副作用的动作必须携带幂等键
• 已发送的消息和已执行的外发动作均属非幂等动作，对此绝不进行重试。
• 指数退避 + 模型降级用于应对 LLM 429

六、总结

从业务层面审视，需要做到以下事项，因为接个模型并不等于完成 LangChain Agent 接入的核心：

1. 架构分离：UI、Agent、编排、工具和宿主分别承担职责
2. 接入次序为：启动服务 → 创建Agent → 进程托管 → UI 面板 → 权限审批
3. 权限、记忆和沙箱

更关键的是，Agent 只是执行和编排任务的框架。要让大模型更好地工作，离不开以下工程化工作：

• prompt 调优
• RAG 向量工程
• 模型微调优
• 业务数据集评测与人工复核指标

这些还将成为更深远的课题！