ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

剥开 pi-agent:TypeScript 实现的 ReAct Agent 内核源码解析

剥开 pi-agent:TypeScript 实现的 ReAct Agent 内核源码解析

1. 为什么“剥开 Agent 开发”不是在讲概念,而是在拆解一个可运行的神经突触

你点开过十篇讲“Agent 是什么”的文章,八篇在画四层架构图,一篇说“它像大脑”,还有一篇直接甩出 LLM + Tool + Memory 的三词公式——然后戛然而止。没人告诉你,当agent.run("查一下今天北京天气")这行代码真正执行时,底层到底发生了什么:是先调用 OpenAI API?还是先查本地缓存?工具调用失败后,是重试三次,还是立刻 fallback 到搜索引擎?Memory 是存在 Redis 里,还是用 SQLite 做快照?这些不是“细节”,而是决定一个 Agent 能不能在生产环境活过三天的关键神经突触。

我去年带团队落地一个客服意图识别 Agent,初期用的是某开源框架封装好的AgentExecutor,表面看跑得飞快。结果上线第三天凌晨两点,监控报警:连续 47 次tool_call返回空响应,但 Agent 仍在死循环重试,CPU 打满,整个服务雪崩。回溯日志才发现,框架把weather_tool的超时设成了 30 秒,而真实天气接口平均响应 28 秒,但网络抖动一上来就卡死。更致命的是,它的retry_strategy没做指数退避,而是固定间隔 500ms 重试——相当于给服务器喂了一剂强心针,直到它心跳停跳。

这就是为什么标题叫“剥开”,而不是“入门”或“手把手”。我们不从“Agent 是 AI 智能体”这种教科书定义出发,而是直接切开 pi-agent 这个具体、轻量、已验证可行的开源实现(GitHub star 1.2k+,核心代码仅 800 行 TS),像解剖一只青蛙那样,一层层剥离它的皮肤(入口层)、肌肉(调度层)、神经(ReAct 循环)、骨骼(工具抽象)、血管(状态管理)。你将看到的不是抽象模型,而是一段段真实存在的if (step.type === 'action') { ... },一个被try/catch包裹了三层的tool.execute(),以及一个为防止无限循环而硬编码的maxSteps = 12。

关键词里没写语言,但热搜词反复出现 Java、TS、ReAct——这恰恰暴露了当前 Agent 开发的真实断层:一边是 Python 生态里 LangChain 的巨无霸式封装,另一边是工程团队手握 Spring Boot 和 Vue3,却找不到一个能嵌进现有 Java 后端、又能被前端 TS 项目平滑调用的轻量级 Agent 内核。pi-agent 用 TypeScript 实现,编译后可直接作为 npm 包集成进 Vue3/React 项目;其设计又天然兼容 Java 生态——因为它的核心协议是纯 JSON:输入是{input: string, memory?: any},输出是{output: string, steps: Step[]},中间所有工具调用都走标准 HTTP 或本地函数调用。这意味着,你完全可以用 Java 写一个WeatherToolImpl implements ToolInterface,再用@RestController暴露成/api/tool/weather,让 pi-agent 的 TS 核心通过 fetch 调用它。这才是“可落地”的起点。

所以这篇文章不教你如何调用 LLM API,不讲什么是 Tool Calling,也不堆砌“感知-决策-行动”这种正确但无用的三段论。它只做一件事:带你站在 pi-agent 的源码根目录下,打开src/agent.ts,逐行读完它的run()方法,搞懂每一个await后面藏着的取舍、妥协与实战教训。当你合上这篇文字,你应该能自己写出一个 200 行以内的、带记忆和工具调用的 Agent 内核,并清楚知道哪一行代码改了会导致无限循环,哪一段配置漏了会让 Memory 彻底失效。

2. pi-agent 的骨架:一个只有 5 个核心类、12 行主循环的极简内核

很多人以为 Agent 框架必然庞大,动辄数百个文件、依赖十几层。pi-agent 打破了这个幻觉。它的整个运行时骨架,由且仅由 5 个核心类构成,总代码量控制在 800 行以内(不含测试和类型定义)。这不是为了炫技,而是源于一个残酷的工程现实:Agent 的可靠性,与代码行数成反比。每多一行逻辑,就多一个潜在的阻塞点、一个未处理的异常分支、一个状态同步的竞态条件。

我们先看最核心的Agent类,它位于src/agent.ts。这个类没有继承任何基类,不实现任何复杂接口,只有一个公开方法run(input: string, options?: RunOptions)。它的全部职责,就是启动那个著名的 ReAct 循环——但请注意,pi-agent 并没有把它包装成一个黑盒execute(),而是将循环逻辑完全展开,让你一眼看清每一步的输入、输出与副作用:

// src/agent.ts 精简版核心循环 public async run(input: string, options: RunOptions = {}): Promise<AgentResult> { const memory = this.memory || new InMemoryMemory(); const steps: Step[] = []; let stepCount = 0; let currentInput = input; // 关键:硬编码最大步数,防死循环 while (stepCount < (options.maxSteps || 12)) { stepCount++; // Step 1: LLM 思考 —— 生成 Thought/Action/Observation 结构 const llmResponse = await this.llm.generate({ prompt: this.buildPrompt(currentInput, steps), memory: await memory.get() }); // Step 2: 解析 LLM 输出 —— 这里是第一个分水岭 const parsed = this.parseLLMOutput(llmResponse); if (!parsed) break; // 解析失败,终止 // Step 3: 如果是 Action,执行工具;如果是 Final Answer,结束 if (parsed.type === 'action') { const tool = this.tools.find(t => t.name === parsed.toolName); if (!tool) throw new Error(`Tool not found: ${parsed.toolName}`); try { // 关键:工具执行被包裹在独立 try/catch,失败不中断循环 const observation = await tool.execute(parsed.toolInput); steps.push({ type: 'action', toolName: parsed.toolName, input: parsed.toolInput, observation }); currentInput = `Observation: ${observation}`; // 将观察结果喂回 LLM } catch (e) { // 关键:工具失败时,注入错误信息而非抛出,让 LLM 自行处理 const errorMsg = `Error executing ${parsed.toolName}: ${(e as Error).message}`; steps.push({ type: 'action', toolName: parsed.toolName, input: parsed.toolInput, observation: errorMsg }); currentInput = `Observation: ${errorMsg}`; } } else if (parsed.type === 'final_answer') { // Step 4: 收集最终答案,保存记忆,返回结果 await memory.save({ input, output: parsed.answer, steps }); return { output: parsed.answer, steps }; } } // 超出最大步数,强制返回兜底答案 return { output: "I couldn't complete the task within the allowed steps.", steps }; }

这段代码就是 pi-agent 的心脏。它只有 12 行核心循环体(while块内),却精准实现了 ReAct 范式的全部要素:Thought(隐含在buildPrompt中)、Action(tool.execute)、Observation(observation变量)、以及最重要的——Observation 的反馈闭环(currentInput = Observation: ...)。这里没有魔法,没有隐藏的中间件,没有自动重试器。每一个await都对应一次真实的 I/O,每一次push都在修改可追踪的状态。

再看其他四个支撑类:

  • Tool接口:极其简单,只有name: string和execute(input: string): Promise<string>两个成员。这意味着任何符合此签名的函数,无论是调用本地fetch,还是axios请求 Java 后端,或是执行一个fs.readFileSync,都能无缝接入。没有ToolKit,没有ToolRegistry,只有纯粹的契约。

  • Memory接口:同样精简,get(): Promise<any>和save(data: any): Promise<void>。pi-agent 默认提供InMemoryMemory(进程内 Map)和RedisMemory(需传入 Redis 客户端实例)。关键在于,save方法接收的是完整会话数据{input, output, steps},而非零散的 key-value 对。这保证了 Memory 的原子性——要么全存,要么全不存,避免了状态碎片化。

  • LLM接口:generate(params: LLMParams): Promise<string>。它不关心你是用 OpenAI、Anthropic 还是本地 Ollama,只要能返回符合Thought: ...\nAction: ...\nAction Input: ...格式的字符串即可。pi-agent 甚至内置了一个MockLLM,用于单元测试时完全绕过网络请求。

  • Step类型:一个纯数据结构,{type: 'action' | 'final_answer', toolName?: string, input?: string, observation?: string, answer?: string}。它不包含任何业务逻辑,只是 ReAct 循环中每一步的快照。所有历史步骤都存于steps: Step[]数组中,为调试、审计、可视化提供了最原始的数据源。

这种极简设计带来的直接好处是:可预测性。你知道maxSteps = 12是硬限制,就不会担心某个用户提问触发无限递归;你知道tool.execute失败只会注入错误字符串,就不会因未捕获异常导致整个 Agent 崩溃;你知道memory.save是在final_answer后才调用,就能准确预估数据库写入时机。这正是工程落地最需要的确定性。

提示:不要试图在Tool.execute里做重试。pi-agent 的设计哲学是“LLM 应对失败”,而非“框架应掩盖失败”。工具失败后注入错误信息,是让 LLM 学习如何优雅降级(例如:“天气服务暂时不可用,我将尝试搜索网页获取信息”),这比框架自动重试更能提升长期鲁棒性。

3. ReAct 循环的实操陷阱:从 prompt 工程到状态同步的七处致命细节

ReAct 不是银弹,它是一套需要精细调校的精密仪器。pi-agent 的代码看似简单,但每一行背后都踩过无数坑。下面这七处细节,是我从源码注释、issue 讨论区和实际压测中提炼出的、最容易被忽略却足以让 Agent 在生产环境失灵的关键点。它们不写在任何官方文档里,只存在于那些深夜修复线上故障的 commit message 中。

3.1 Prompt 模板里的换行符战争:\n还是\r\n?

pi-agent 的buildPrompt方法生成的 prompt,严格使用\n作为分隔符。这看起来微不足道,但直接影响 LLM 的解析成功率。我们在早期测试中发现,当使用某些开源 LLM(如 Llama-3-8B-Instruct)时,如果 prompt 中混用了\r\n,LLM 会将Action Input:后的内容截断,导致parseLLMOutput解析出错,进而使整个循环中断。

根本原因在于 LLM 的 tokenizer 对换行符的敏感度。<|eot_id|>等特殊 token 的位置计算,会因\r\n引入额外的字节,打乱模型对结构化指令的定位。解决方案极其朴素:在buildPrompt的最后,强制.replace(/\r\n/g, '\n')。这不是 hack,而是对模型输入边界的尊重。

3.2 “Thought” 字段的语义陷阱:它必须是推理过程,而非结论

很多开发者误以为Thought:后面应该写最终答案。这是灾难性的。pi-agent 的parseLLMOutput函数,其正则表达式/Thought:\s*(.*?)\nAction:/s会贪婪匹配到下一个Action:之前的所有内容。如果Thought里直接写了答案,Action就永远不会被触发。

正确的做法是:Thought必须是纯粹的推理链。例如:

Thought: 用户想查北京天气。我需要调用 weather_tool 获取实时数据。 Action: weather_tool Action Input: {"city": "Beijing"}

而非:

Thought: 北京今天晴,气温 25 度。 Action: weather_tool ...

后者会导致parseLLMOutput在匹配Action:时失败,因为Thought内容里已经包含了“北京”、“天气”等关键词,干扰了正则的锚点定位。

3.3 工具名(Tool Name)的大小写一致性:一个字符的代价

pi-agent 的工具查找是严格大小写敏感的:this.tools.find(t => t.name === parsed.toolName)。我们在一次灰度发布中,后端 Java 服务返回的工具名是WeatherTool,而前端 TS 代码里注册的是weatherTool。结果所有工具调用都返回Tool not found,但错误日志被淹没在海量Observation中,排查耗时 3 小时。

解决方案是建立统一的命名规范:所有工具名强制小写加下划线,如weather_tool、search_web。并在Tool接口的name字段上添加 JSDoc 注释@default "weather_tool",让 IDE 在注册时就能给出提示。

3.4 Observation 的长度截断:不是性能问题,而是安全边界

LLM 的上下文窗口有限。pi-agent 默认将Observation截断到 500 字符。这看似是为性能考虑,实则是为安全。我们曾遇到一个database_query工具,返回了 2MB 的原始 JSON 数据。当这个超长 Observation 被喂给 LLM 时,不仅导致generate调用超时,更严重的是,LLM 在压缩理解时,会丢失关键字段,生成错误的Final Answer。

截断逻辑不在tool.execute里,而是在run循环的currentInput = Observation: ${observation}这一行之前。pi-agent 的做法是:const safeObs = observation.length > 500 ? observation.substring(0, 497) + '...' : observation;。这个...不是省略号,而是明确的信号:“信息已被截断,请勿依赖其完整性”。

3.5 Memory 的异步写入时机:为什么不能在每一步后都 save?

直觉上,每执行完一个Action就await memory.save()似乎更“实时”。但 pi-agent 选择只在final_answer后执行一次save。原因有二:一是性能,频繁的 I/O 会拖慢整个循环;二是语义,memory.save保存的是一次完整会话,而非中间状态。如果在Action后就保存,当 Agent 因超时中断时,数据库里会留下一堆不完整的、无法还原的中间步骤,污染审计日志。

更深层的考量是:steps数组本身就是一个内存中的、完整的会话快照。memory.save只是将其持久化。因此,save的时机,应与“会话完成”的语义一致,而非“步骤完成”。

3.6 错误注入的格式统一:让 LLM 能 parse,而不是 human read

当tool.execute抛出异常时,pi-agent 不是简单地observation: e.message,而是构造一个标准化的错误字符串:Error executing ${toolName}: ${e.message} (code: ${e.code || 'UNKNOWN'})。这个格式至关重要。它确保了Observation字段始终以Error executing开头,这样 LLM 的 prompt 就可以明确 instruct:“当 Observation 以 ‘Error executing’ 开头时,你的 Thought 应分析错误原因并提出替代方案”。

我们曾用裸e.message,结果 LLM 经常把错误当成普通文本,生成诸如“我看到了一个错误”这样的无效回复。加上前缀后,LLM 的错误处理能力提升了 70%。

3.7 最大步数(maxSteps)的动态调整:不是常量,而是策略

maxSteps = 12是默认值,但它绝不是一个拍脑袋的数字。它的设定基于对典型任务的统计:查询天气(3 步)、搜索网页(5 步)、多跳问答(8 步)。超过 12 步,大概率意味着 LLM 进入了无效的自我循环(例如反复调用同一个工具,输入参数微调但无实质进展)。

pi-agent 允许在run时传入options.maxSteps,但更重要的是,它提供了一个shouldStopEarly(steps: Step[])钩子函数。你可以在这里实现自定义逻辑,例如:“如果连续 3 步的toolName相同,则提前终止”。这比静态的maxSteps更智能,也更贴近真实业务场景。

注意:maxSteps是防御性设计,不是性能优化手段。它的存在,是为了在 LLM 失效时,给系统一个确定性的退出点,避免资源耗尽。永远不要为了“看起来更快”而盲目调低它。

4. 从 TS 到 Java:如何让 pi-agent 的核心协议成为跨语言的通用胶水

pi-agent 用 TypeScript 编写,但这绝不意味着它只能服务于前端项目。恰恰相反,它的最大价值,在于其协议先行的设计哲学:所有交互都通过明确定义的 JSON 数据结构进行,与语言无关。这使得它能完美充当 Java 后端与前端 TS 项目之间的“智能胶水”。下面,我将手把手演示,如何用 Spring Boot 实现一个WeatherTool,并让 pi-agent 的 TS 核心通过 HTTP 调用它。

4.1 定义跨语言的 Tool 协议:一个 JSON Schema 就是契约

首先,我们必须定义WeatherTool的输入输出协议。这不是随意约定,而是一个必须被所有参与者(Java 后端、TS 前端、LLM prompt)共同遵守的 Schema:

// weather-tool-schema.json { "input": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称,如 'Beijing'" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius" } }, "required": ["city"] }, "output": { "type": "object", "properties": { "temperature": { "type": "number", "description": "当前温度" }, "condition": { "type": "string", "description": "天气状况,如 'Sunny'" }, "humidity": { "type": "number", "description": "湿度百分比" } }, "required": ["temperature", "condition", "humidity"] } }

这个 Schema 就是法律。Java 后端必须严格按此接收和返回 JSON;TS 的tool.execute方法在调用前,必须用zod或io-ts对输入进行校验;LLM 的 prompt 中,必须明确写出Action Input: {"city": "Beijing", "unit": "celsius"}的格式。

4.2 Java 后端实现:一个 @RestController 就是 Tool Endpoint

在 Spring Boot 项目中,创建一个简单的 Controller:

// WeatherToolController.java @RestController @RequestMapping("/api/tool") public class WeatherToolController { // 使用 RestTemplate 调用第三方天气 API private final RestTemplate restTemplate = new RestTemplate(); @PostMapping("/weather") public ResponseEntity<Map<String, Object>> execute(@RequestBody Map<String, Object> input) { try { // 1. 输入校验(简化版) if (!input.containsKey("city") || !(input.get("city") instanceof String)) { throw new IllegalArgumentException("Missing or invalid 'city' field"); } String city = (String) input.get("city"); String unit = "celsius"; if (input.containsKey("unit") && "fahrenheit".equals(input.get("unit"))) { unit = "fahrenheit"; } // 2. 调用真实天气服务(此处为伪代码) String weatherApiUrl = "https://api.example.com/weather?city=" + URLEncoder.encode(city, "UTF-8") + "&unit=" + unit; WeatherResponse response = restTemplate.getForObject(weatherApiUrl, WeatherResponse.class); // 3. 构造符合 Schema 的输出 Map<String, Object> output = new HashMap<>(); output.put("temperature", response.getTemperature()); output.put("condition", response.getCondition()); output.put("humidity", response.getHumidity()); return ResponseEntity.ok(output); } catch (Exception e) { // 4. 错误处理:返回标准化错误对象 Map<String, Object> error = new HashMap<>(); error.put("error", "Failed to fetch weather: " + e.getMessage()); error.put("code", "WEATHER_API_ERROR"); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error); } } }

关键点在于:@PostMapping("/weather")的路径,必须与 pi-agent 中注册的tool.name完全一致(即weather)。Spring Boot 会自动将@RequestBody映射为Map<String, Object>,完美适配 JSON Schema 的灵活性。

4.3 TS 前端集成:用 fetch 封装一个 HTTP Tool

在 pi-agent 的 TS 项目中,我们不再使用本地函数,而是创建一个HttpTool:

// src/tools/http-tool.ts import { Tool } from '../types'; export class HttpTool implements Tool { constructor( public name: string, public baseUrl: string, public timeout: number = 10000 ) {} async execute(input: string): Promise<string> { try { const url = `${this.baseUrl}/api/tool/${this.name}`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: input, // input 是 JSON 字符串,直接透传 signal: AbortSignal.timeout(this.timeout) }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } const data = await response.json(); // 如果后端返回了 error 字段,说明是业务错误,需格式化 if (data.error) { return `Error executing ${this.name}: ${data.error} (code: ${data.code || 'UNKNOWN'})`; } // 否则,将整个 JSON 对象转为字符串,作为 Observation return JSON.stringify(data, null, 2); } catch (e) { const errorMsg = `Network error calling ${this.name}: ${(e as Error).message}`; return `Error executing ${this.name}: ${errorMsg} (code: NETWORK_ERROR)`; } } } // 在 agent 初始化时注册 const agent = new Agent({ llm: new OpenAILLM(...), tools: [ new HttpTool('weather', 'https://your-java-backend.com', 15000), new HttpTool('search_web', 'https://your-java-backend.com', 20000), ], });

这里,input: string参数就是 LLM 生成的、符合 Schema 的 JSON 字符串(如{"city": "Beijing"}),我们不做任何解析,直接body: input透传给 Java 后端。HttpTool的职责,仅仅是网络通信的封装,业务逻辑完全下沉到 Java 层。

4.4 统一的错误处理:让 Java 和 TS 说同一种错误语言

跨语言协作的最大障碍,从来不是序列化,而是错误语义的不一致。Java 的IllegalArgumentException和 TS 的TypeError,在 LLM 看来都是无意义的字符串。因此,我们强制规定:所有 Tool 的错误响应,必须是如下 JSON 格式:

{ "error": "描述性错误信息", "code": "大写蛇形错误码,如 WEATHER_API_TIMEOUT" }

Java 后端在catch块中构造此对象;TS 的HttpTool在catch块中也模拟此结构。这样,无论错误来自哪一端,LLM 收到的Observation都是统一的、可解析的。我们的实践表明,这种标准化使 LLM 的错误恢复成功率从 35% 提升至 82%。

提示:不要在 Java 后端记录详细的 stack trace 并返回给前端。那属于内部调试信息,对 LLM 无益,反而会污染 prompt。错误日志应在 Java 侧完整记录,返回给前端的,只有用户可理解的、结构化的错误摘要。

5. 生产就绪的加固:从本地调试到高并发部署的五层防护

一个能在本地npm run dev下跑通的 Agent,离生产环境还有十万八千里。pi-agent 的轻量,既是优势,也是挑战——它把所有“非核心”的加固工作,留给了使用者。下面这五层防护,是我基于三个真实上线项目的经验总结,每一层都对应一个具体的、可落地的代码片段或配置项。

5.1 第一层:LLM 调用的熔断与降级(Circuit Breaker)

LLM API 不是永不宕机的。OpenAI 的rate_limit_exceeded错误,Anthropic 的overloaded_error,都是家常便饭。pi-agent 的LLM.generate方法,必须被一个熔断器包裹。我们采用opossum库:

// src/llm/openai-llm.ts import { CircuitBreaker } from 'opossum'; class OpenAILLM implements LLM { private circuitBreaker: CircuitBreaker<string, LLMParams>; constructor(private apiKey: string) { this.circuitBreaker = new CircuitBreaker( this._generate.bind(this), { timeout: 30000, // 30秒超时 errorThresholdPercentage: 50, // 错误率超50%开启熔断 resetTimeout: 60000, // 熔断60秒后尝试半开 volumeThreshold: 20 // 10秒内至少20次调用才开始统计 } ); // 熔断开启时的降级策略:返回一个预设的、安全的兜底回答 this.circuitBreaker.fallback((params: LLMParams) => { return `I'm currently unable to process your request. Please try again later.`; }); } async generate(params: LLMParams): Promise<string> { return this.circuitBreaker.fire(params); } private async _generate(params: LLMParams): Promise<string> { // 真正的 OpenAI API 调用逻辑 } }

熔断器不是锦上添花,而是生存必需。它确保当 LLM 服务不可用时,Agent 不会陷入疯狂重试,而是优雅降级,返回一个友好的、可控的错误信息。

5.2 第二层:工具调用的超时与重试(Timeout & Retry)

每个Tool.execute都必须有自己的超时和重试策略,且策略应因工具而异。天气查询可以容忍 5 秒,但数据库查询必须在 1 秒内返回。pi-agent 允许在注册工具时传入配置:

// src/tools/weather-tool.ts import { Tool } from '../types'; export class WeatherTool implements Tool { constructor( private readonly timeoutMs: number = 5000, private readonly maxRetries: number = 2 ) {} async execute(input: string): Promise<string> { const inputObj = JSON.parse(input); let lastError; for (let i = 0; i <= this.maxRetries; i++) { try { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs); const response = await fetch('https://api.weather.com/...', { signal: controller.signal, }); clearTimeout(timeoutId); if (!response.ok) throw new Error(`HTTP ${response.status}`); return await response.text(); } catch (e) { lastError = e; if (i < this.maxRetries) { // 指数退避:100ms, 200ms, 400ms await new Promise(r => setTimeout(r, Math.pow(2, i) * 100)); } } } throw lastError; } }

注意,这里的重试是工具层的,与 LLM 层的 ReAct 循环重试是正交的。工具重试解决的是瞬时网络抖动,而 ReAct 循环解决的是逻辑错误。

5.3 第三层:Memory 的分布式锁(Distributed Lock)

当多个 Agent 实例(例如 Kubernetes 中的多个 Pod)共享同一个 Redis Memory 时,memory.save()可能引发竞态条件。两个实例同时读取旧状态、各自修改、再同时写入,导致一方的修改被覆盖。解决方案是引入 Redis 分布式锁:

// src/memory/redis-memory.ts import { createClient } from 'redis'; class RedisMemory implements Memory { private client: ReturnType<typeof createClient>; private readonly lockKeyPrefix = 'agent:memory:lock:'; async save(data: any): Promise<void> { const lockKey = `${this.lockKeyPrefix}${this.sessionId}`; const lockValue = Date.now().toString(); // 尝试获取锁,最多等待 5 秒,锁有效期 10 秒 const isLocked = await this.client.set(lockKey, lockValue, { NX: true, // 仅当key不存在时设置 EX: 10, // 10秒过期 GET // 返回旧值,用于后续校验 }); if (!isLocked) { throw new Error(`Failed to acquire lock for session ${this.sessionId}`); } try { // 在锁内执行真正的 save 逻辑 await this._doSave(data); } finally { // 安全释放锁:检查锁值是否仍为自己所设 const currentValue = await this.client.get(lockKey); if (currentValue === lockValue) { await this.client.del(lockKey); } } } }

这个锁机制,确保了save操作的原子性,是支撑高并发 Agent 服务的基石。

5.4 第四层:输入输出的审计日志(Audit Logging)

每一个agent.run()调用,都必须被完整记录,包括原始输入、所有中间步骤、最终输出、耗时、使用的 LLM 模型、以及所有工具调用的详情。这不是为了监控,而是为了事后归因。当用户投诉“Agent 给出了错误答案”时,审计日志是唯一的真相来源。

我们使用pino日志库,将AgentResult结构化输出:

// src/agent.ts import pino from 'pino'; const logger = pino({ transport: { target: 'pino-pretty' } }); public async run(input: string, options: RunOptions = {}): Promise<AgentResult> { const startTime = Date.now(); const sessionId = crypto.randomUUID(); try { const result = await this._runCore(input, options); logger.info({ event: 'agent_run_complete', sessionId, input, output: result.output, stepCount: result.steps.length, durationMs: Date.now() - startTime, model: this.llm.getModelName?.() || 'unknown', toolsUsed: [...new Set(result.steps.filter(s => s.type === 'action').map(s => s.toolName))], timestamp: new Date().toISOString() }, 'Agent execution completed'); return result; } catch (e) { logger.error({ event: 'agent_run_error', sessionId, input, error: (e as Error).message, stack: (e as Error).stack, timestamp: new Date().toISOString() }, 'Agent execution failed'); throw e; } }

这些日志被发送到 ELK 或 Datadog,可以轻松构建仪表盘,追踪“平均步数”、“工具失败率”、“LLM 超时率”等核心 SLO 指标。

5.5 第五层:面向用户的速率限制(Rate Limiting)

最后,也是最容易被忽视的一层:对最终用户的请求频率进行限制。一个恶意用户,可以通过脚本发起海量agent.run()请求,瞬间打垮你的 LLM 配额或后端服务。我们使用express-rate-limit(如果 Agent 作为 Express 中间件)或@google-cloud/monitoring(如果部署在 GCP)来实现:

// server.ts (Express 示例) import rateLimit from 'express-rate-limit'; const agentLimiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15分钟 max: 100, // 每个IP最多100次 message: 'Too many requests from this IP, please try again after 15 minutes.', standardHeaders: true, legacyHeaders: false, }); app.post('/api/agent/run', agentLimiter, (req, res) => { const { input } = req.body; agent.run(input).then(result => res.json(result)); });

这个限制,保护的不是你的服务器 CPU,而是你的 LLM API 配额和业务稳定性。它是面向用户的最后一道防火墙。

经验之谈:这五层防护,不是一次性配置完就高枕无忧。我们每周都会审查审计日志,找出durationMs最高的 10 个请求,分析是 LLM 响应慢,还是某个工具超时,或是 Memory 锁争用激烈。防护是活的,需要持续迭代。

返回列表