前言

上一篇我们论证了 AI 产品为什么需要内置本地 Agent！怎么说呢，

现在我们来聚焦"怎么做" —— 从架构设计到代码接入。输出我们的落地方案，说起来，

一、整体架构：五层分离

五层职责这方面。

• 前端不要直接去调模型，用服务封装一个本地 Agent Runtime。按理说，
• API Key 不能暴露给前端。工具执行需要统一收口，后续加能力不用推翻前端。
• LangChain 用来快速起步。LangGraph 用来做复杂编排，工具层基于业务 去封装。

二、接入步骤

Step ：建立本地 Agent 服务

新建 ai-agent-server/workspace，基于 Hono 框架提供 HTTP 服务：

// apps/ai-agent-server/src/server.ts
import { Hono } from 'hono';import { serve } from '@hono/node-server';export const createAiAgentServer = async => {
const app = new Hono;// 健康检查
app.get => c.json);// 问答接口
registerChatRoutes;const server = serve;return {
origin的观点是，`http://${config.host}:${server.address.port}`。close: => /* ... */
};}，

关键点：

• 服务跑在 .:,只监听本地。
• API Key只存在服务端环境变量，不进前端 bundle。怎么说呢，

Step ：接入 LangChain createAgent

最小 Agent 接入——先做普通问答。工具后续再加：

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

SSE 流式接口：

// apps/ai-agent-server/src/routes/chat.ts
export const registerChatRoutes = => {
const agent = createHomeAiQaAgent;app.post => {
const body = await c.req.json;const stream = await agent.stream(
{ messages: body.messages }。{
encoding:'text/event-stream',streamMode:,}
);return new Response(stream,{
headers:{
'Content-Type':'text/event-stream'。'Cache-Control':'no-cache'
}
});})，};

Step ：Electron 托管进程

Lets let Agent 服务随应用自动启动。态用 ,打包态用 fork：

// electron/src/main/processManager/aiAgentProcess/index.ts
export const startAiAgentProcess==>{
if{
说到//打包态。fork 打包后的 js 文件
aiAgentProcess=childProcess.fork,);}else{
//开发态这方面，pnpm 启动 dev server
aiAgentProcess=childProcess.spawn;}
}

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

// 前端调用const runtime=await window.LinkService.request;//runtime={ready:true,status:'ready',baseUrl:'http://.'}

Step ：前端面板接入

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

// apps/src/features/home/components/AiQaPanel/index.tsx
import { FetchStreamTransport。useStream}from '@langchain/langgraph-sdk/react';const AiQaPanel==>{
const transport=useMemo=>new FetchStreamTransport({
从apiUrl来看。`${runtime.baseUrl}/api/agent`,}),);const stream=useStream;return (

AI 问答

{stream.messages.map}
setInput} />
stream.submit}>发送
);
}，

Step ：权限审批机制 

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


使用 LangGraph 的 interrupt 实现审批中断：
arduino
// Agent 调用高风险工具时interrupt 等待使用者审批// 使用者点击"允许"后resume继续执行
前端渲染审批卡片：
ts
AiAgentApis.approveRequest} onDeny={=>AiAgentApis.denyRequest}/>
不是所有工具都该暴露给模型，Tool Registry 是能力全集，Agent 每次可见的是权限过滤后的子集。

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


短期记忆 : 基于 thread_id 的状态持久化。保存当前会话的：


消息历史;

任务计划;

已调用工具结果;

中断点;老实说，

使用 LangGraph 的 checkpointer 实现。阶段用 MemorySaver。生产用 PostgresSaver。按理说，
    

Short-term memory保留过程；long-term memory保留结论.

短期记忆保留过程

长期记忆保留结论。

三、短期记忆



基于 thread_id 的状态持久化；保存当前会话的：







消息历史;



任务计划;



已调用工具结果;



中断点;


使用 LangGraph 的 checkpointer 实现；阶段用 MemorySaver；生产用 PostgresSaver。不过，**

跨会话持久保存：





使用者偏好；



授权偏好；


​

常用操作模板；​
"关键判断": "不是所有内容都该记住"；只保存三类：使用者显式要求记住的、高频重复出现对后续有帮助的、权限与偏好类配置。**


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

简单任务 →直接用 Agent ReAct 循环。*

复杂任务 → 用 LangGraph StateGraph 显式编排。不过，*

推荐的任务编排层次：



风险等级
典型操作
默认策略

low
读笔记、读线程上下文自动执行

medium
新建文档、导出 PDF首次确认。可记住
high
Shell 命令、发消息必须逐次审批
critical
删除文件、批量外发默认拒绝





Intent Classifier识别意图：问答 / 查询 /生成 / 执行 / 工作流Planner拆解目标为可执行步骤Supervisor调度子代理 、 审批 、 重试Executor执行工具或子图Verifier检查结果是否完整.






简单问题让 Agent 自由思考。复杂任务让 Graph 显式编排。


五 错误处理与并发 *

错误分类








错误类型；

示例；说起来，

处理；





|model_error | 超时,429 自动重试 / 模型降级 | |

|tool_error | 参数错误让 Agent 自修复 | |

|permission_error | 审批被拒中断提示使用者 | |

|sandbox_error | 方法非法终止并诊断 | |

重试原则





• 幂等是重试前提 : 涉及副作用的动作必须带幂等键；

• 非幂等动作绝不重试 : 已发送的消息已执行的外发动作；其实，

• LLM 用指数退避+ 模型降级.


六

从业务角度看。需要：

① 分离架构 : UI 、 Agent 、 编排 、 工具 、 宿主各司其职。

② 分步接入 : 开启服务 → 创建 Agent →进程托管 → UI 面板 → 权限审批。

③ 权限,内存,沙箱

更主要的是 : “代理”只是框架而已。要让大模型更好工作，还得靠工程化 :





• prompt 调优;

• RAG 向量工程;

• 模型微调;

• 数据集评测人工复核指标;

这些，将是更深远课题！