2026/8/12 9:59:35
FEATURED · 精选文章 
1. 项目概述为什么我要从零造一个 Agent 运行时最近几个月AI Agent 这个概念火得不行从技术社区到产品讨论几乎人人都在谈。作为一个在软件架构和分布式系统领域摸爬滚打了十多年的老码农我本能地对各种“新概念”保持警惕但这次Agent 确实让我坐不住了。不是因为它听起来多酷而是因为我发现市面上现有的那些 Agent 框架、运行时用起来总感觉“隔靴搔痒”。要么是封装得太重像个黑盒出了问题你都不知道从哪查起要么就是太轻只给了你几个 API 和概念剩下的“脏活累活”全得自己来美其名曰“灵活”实则增加了巨大的认知和工程负担。所以我决定自己动手造一个 Agent 运行时。这个决定不是一时冲动而是基于过去几个月里我尝试用各种框架去构建实际业务 Agent 时踩过的无数个坑。比如任务调度混乱导致死锁、记忆管理不当让 Agent“失忆”、工具调用异常时整个流程崩掉却难以定位……这些问题在那些追求“大而全”或“小而美”的框架里往往被隐藏或简化了但恰恰是构建稳定、可靠、可调试的 Agent 应用最关键的部分。我这个项目标题叫“造一个 Agent 运行时 #01:我决定开干,顺便把坑都写下来”。#01 意味着这是一个系列我会把从零开始的设计、编码、测试、优化全过程以及其中遇到的每一个技术决策、每一个踩到的坑都原原本本地记录下来。它不会是一个追求功能最全的“轮子”而会是一个追求“透明”、“可控”和“可学习”的实践样本。我希望通过这个系列不仅能让自己对 Agent 的核心机制有更透彻的理解也能给那些同样被各种框架搞得晕头转向或者想深入理解 Agent 内部工作原理的开发者提供一个可以亲手拆卸、组装的“教学引擎”。简单说这个运行时项目目标用户就是像我一样的实践派开发者我们关心架构的清晰度胜过功能的堆砌关心问题的可调试性胜过接口的华丽度关心核心原理的掌握胜过 API 的简单调用。接下来我会详细拆解我对这个 Agent 运行时的核心设计思路、将要实现的关键模块以及我预见到和已经遇到的那些“坑”。2. 核心设计思路与架构选型2.1 定义我们的“运行时”边界首先我们必须明确“运行时”在这里指什么。在 Agent 的语境下它不是一个像 JVM 或 .NET CLR 那样的通用程序执行环境。我们的 Agent 运行时更准确地说是一个“智能体生命周期管理与任务协调引擎”。它的核心职责是接管一个或多个 Agent 的“大脑”LLM、“记忆”、“工具”和“感知”并驱动它们按照既定策略如 ReAct Chain of Thought去执行任务处理任务执行过程中的状态流转、异常、并发与通信。因此我们的运行时不会去实现 LLM 本身那是 OpenAI、 Anthropic 或本地模型的事也不会去实现具体的工具函数那是开发者的事。我们的焦点在于粘合层和调度层。基于这个定位我画出了第一版的核心架构图在脑海里下文用文字描述Agent 核心Agent Core这是运行时管理的单元。每个 Agent 实例包含身份ID、名称、角色描述、一个 LLM 客户端配置、一个记忆系统引用和一组可用工具。任务队列与调度器Task Queue Scheduler接收外部或内部产生的任务Task将其放入队列。调度器负责从队列中取出任务分配给合适的 Agent 实例执行。这里要处理优先级、超时、重试等策略。执行引擎Execution Engine这是运行时的心脏。它驱动一个任务的完整执行循环。例如对于一个 ReAct 循环引擎需要a) 结合任务描述和记忆构造给 LLM 的提示词b) 调用 LLM 并解析其输出是思考还是调用工具还是最终回答c) 如果调用工具则安全地执行工具函数并获取结果d) 将本轮的结果更新到记忆对话历史或长期记忆e) 判断循环是否继续达到最大步数、LLM 输出最终答案、或出错。记忆管理系统Memory System提供短期如对话上下文窗口和长期如向量数据库的记忆存储与检索能力。运行时需要提供标准的记忆接口并能在执行引擎的适当时机自动调用“保存”和“读取”操作。工具管理器Tool Manager负责注册、发现和管理所有可用的工具函数。它需要提供安全的沙箱环境尤其是对于不可信的工具代码处理工具的输入输出序列化并在工具执行失败时提供清晰的错误信息。可观测性与日志Observability Logging这是调试复杂 Agent 行为的生命线。运行时必须内置结构化的日志记录每一个关键步骤任务入队、调度决策、LLM 请求与响应可脱敏、工具调用与结果、记忆操作、异常事件等。最好能支持 OpenTelemetry 这样的标准方便接入现有的监控体系。2.2 技术栈选型背后的“为什么”选择合适的技术栈是项目成功的基石。我的选型原则是成熟、轻量、可控、社区活跃。编程语言TypeScript/Node.js为什么Agent 生态目前与 JavaScript/TypeScript 结合非常紧密大量的工具、前端集成、云函数部署都围绕此生态。Node.js 的非阻塞 I/O 模型非常适合处理 Agent 任务中大量的网络 I/O调用 LLM API、访问数据库、调用外部 API。TypeScript 的静态类型系统能在编码阶段就捕获大量潜在错误这对于构建一个复杂的、异步的运行时系统至关重要。备选考虑Python 在 AI 领域有统治地位但其在大型并发服务、类型安全尽管有 MyPy和前后端一体化方面我个人觉得不如 TS/Node.js 栈顺手。Go 或 Rust 性能极佳但生态上对于快速集成各种 LLM SDK 和 Web 工具链目前还是 TS/Node.js 更丰富。核心依赖LangChain.js / LangGraph不直接使用其高层 API但会深度参考其设计。LangChain 定义了很好的抽象如BaseChatModel,BaseTool,BaseMemory我们可以实现兼容这些接口的组件这样用户已有的部分 LangChain 工具或记忆体可以无缝接入。更重要的是学习它的设计能避免我们重复造一些基础轮子。Zod用于运行时输入验证和类型推断。在 Agent 系统中LLM 的输出是不稳定的字符串我们需要将其解析为结构化的数据如工具调用参数。Zod 能让我们安全、声明式地定义这些结构并给出清晰的验证错误信息这比手动写if-else强太多。Pino高性能的结构化 JSON 日志记录器。Agent 运行时的日志量会很大结构化日志便于后续通过 ELK 或类似工具进行检索和分析。RxJS / 或自定义 EventEmitter用于实现运行时的内部事件驱动机制。例如“任务完成”、“工具调用开始”、“记忆更新”都可以作为事件发出方便内部模块解耦也便于外部监听进行扩展。存储与外部服务记忆存储短期记忆对话历史可以用内存或 Redis。长期记忆向量检索初期计划支持pgvectorPostgreSQL 扩展和Chroma轻量级向量数据库通过抽象接口实现方便切换。任务队列初期为了简化可能用内存队列或基于 Redis 的Bull库。在生产环境需要考虑更健壮的分布式队列如RabbitMQ或Apache Kafka。注意技术栈不是一成不变的。在系列文章中我可能会因为遇到具体问题而调整选型。例如如果发现 Node.js 的单个进程在复杂推理链中成为瓶颈我们可能会讨论引入工作线程Worker Threads或甚至将执行引擎部分用 Rust 重写为 Native Addon 的可能性。这就是“写下来”的价值——记录决策的演变过程。3. 核心模块深度拆解与实现难点3.1 执行引擎ReAct 循环的稳健实现执行引擎是运行时的核心算法部分。我们以最经典的 ReActReasoning Acting模式为例。一个健壮的 ReAct 引擎需要处理以下关键问题1. 提示词工程与上下文管理引擎需要动态构造每次请求 LLM 的提示词。这包括系统角色设定、任务描述、相关记忆从记忆系统检索、之前的步骤历史思考、行动、观察、以及当前可用的工具列表及其描述。难点在于上下文长度限制。我们需要一个“上下文窗口管理器”当历史超过模型限制时能智能地总结、压缩或丢弃最不重要的部分而不是粗暴地截断。初期实现可能会采用简单的“滑动窗口”法后期再引入更复杂的摘要策略。2. LLM 输出的解析与路由LLM 的输出是一段文本。我们需要从中解析出结构化意图是“思考”Thought: ...是“行动”Action: 工具名\nAction Input: {...}还是“最终答案”Final Answer: ...。这里极易出错。实现方案我们会强制要求 LLM 以严格的格式如 JSON 或特定的分隔符输出。使用 Zod 来定义ToolCall和FinalAnswer的 schema对 LLM 的原始输出进行解析和验证。如果解析失败引擎不能直接崩溃而应进入“修复”流程例如将错误信息和原始输出再次发给 LLM要求其纠正格式。代码示意概念// 定义工具调用响应的结构 const ToolCallSchema z.object({ action: z.string(), action_input: z.record(z.any()) }); type ToolCall z.infertypeof ToolCallSchema; // 在引擎中解析 try { const parsed ToolCallSchema.safeParse(JSON.parse(llmOutput)); if (parsed.success) { // 这是一个工具调用 await handleToolCall(parsed.data); } else { // 尝试解析为最终答案或其他格式... } } catch (error) { // 格式解析失败进入错误处理流程 await handleParseError(llmOutput, error); }3. 工具执行的隔离与安全这是运行时安全性的关键。我们不能让 Agent 随意调用任何系统命令或访问敏感数据。沙箱方案在 Node.js 环境下对于简单、可信的工具如计算器、HTTP GET 请求可以直接执行。对于不可信或高风险工具必须考虑隔离。方案包括a) 使用worker_threads在独立线程中运行b) 使用 Docker 容器运行工具代码c) 通过 RPC 调用部署在安全环境中的服务。初期我们会实现一个基础的SafeToolExecutor它至少会在调用前后进行参数校验和输出过滤并记录完整的调用溯源。4. 循环控制与终止条件引擎必须避免陷入无限循环。我们需要设置明确的终止条件最大迭代步数如 20 步。超时时间如整个任务 2 分钟。LLM 明确输出最终答案。用户手动中断。 引擎需要维护每一步的状态并在每次循环开始前检查这些条件。3.2 记忆系统不仅仅是聊天历史记忆是 Agent 持续学习和保持会话连贯性的基础。我们的记忆系统需要分层设计短期记忆Short-term Memory / Buffer存储当前会话的完整交互历史用户消息、Agent 的思考、工具调用、观察结果。通常受限于 LLM 的上下文长度。实现上可以是一个数组并附带一个“窗口管理器”来处理长度限制。长期记忆Long-term Memory用于存储超越上下文窗口的重要信息并通过语义检索在需要时召回。这通常涉及向量数据库。实现难点如何决定什么信息该存入长期记忆是每轮对话都存还是只存 LLM 认为重要的摘要我们初期会采用一个简单策略在任务结束时由引擎触发让 LLM 对本次任务的关键信息进行总结然后生成嵌入向量存入向量库。检索时将当前问题或上下文向量化从向量库中查找最相关的几条记忆注入到短期记忆的提示词中。记忆的键值对存储除了对话Agent 可能需要记住一些简单的事实如用户偏好user_123.prefers_dark_mode true。我们可以提供一个简单的键值对存储接口底层可以用内存、Redis 或数据库。实操心得记忆系统的设计很容易过度工程化。我的建议是先从最简单的“对话历史数组”开始确保核心执行链路跑通。然后再逐步加入向量检索等高级功能。同时一定要为记忆操作设计详细的日志否则当 Agent 行为诡异时你根本不知道它“记住”或“忘记”了什么。3.3 任务调度与并发处理当有多个任务需要处理或者一个任务可以分解为多个子任务时调度器就至关重要。单 Agent 多任务一个 Agent 实例同时只能处理一个任务。我们需要一个任务队列来管理待办任务。调度器可以采用简单的 FIFO先进先出也可以支持优先级。多 Agent 协作这是更复杂的场景。例如一个“规划者”Agent 将大任务分解然后分配给多个“执行者”Agent。这要求运行时支持 Agent 间的通信。初期我们可以通过一个共享的“黑板”Blackboard系统来实现这是一个共享的键值存储空间Agent 可以将中间结果写在上面其他 Agent 可以读取。并发与资源限制同时向 LLM API 发起大量请求可能会触发速率限制。调度器需要实现一个“令牌桶”或类似的限流机制控制对昂贵资源如 GPT-4 API的并发访问。实现难点状态管理。在分布式环境下任务状态、Agent 状态、记忆状态可能分布在不同的服务或数据库中。如何保证一致性我们初期会以单进程为主状态保存在内存和本地数据库简化这个问题。但架构上要为未来的分布式扩展留出接口例如使用 Redis 作为集中式的状态存储和消息总线。4. 从零开始的实操搭建记录4.1 项目初始化与基础结构搭建首先我们创建一个新的 TypeScript 项目。mkdir agent-runtime-core cd agent-runtime-core npm init -y安装核心依赖npm install typescript ts-node types/node --save-dev npm install zod pino rxjs # 后续会安装 LLM SDK (如 openai) 和向量数据库客户端配置tsconfig.json设置严格的类型检查。然后创建我们的核心目录结构src/ ├── core/ │ ├── Agent.ts # Agent 核心类定义 │ ├── Task.ts # 任务定义 │ ├── Engine.ts # 执行引擎 │ └── Scheduler.ts # 调度器 ├── memory/ │ ├── ShortTermMemory.ts │ ├── LongTermMemory.ts │ └── interfaces.ts ├── tools/ │ ├── Tool.ts # 工具基类 │ ├── ToolManager.ts │ └── builtin/ # 内置工具 ├── llm/ │ └── clients/ # 对接不同 LLM 提供商 ├── index.ts # 主出口文件 └── utils/ └── logger.ts # 日志工具我们先从定义基础接口开始。在src/core/interfaces.ts中// 一个任务的最小定义 export interface ITask { id: string; description: string; // 任务描述 input?: any; // 任务输入数据 priority?: number; createdAt: Date; } // Agent 的配置 export interface IAgentConfig { id: string; name: string; role: string; // 角色描述用于系统提示词 llmClient: ILlmClient; // LLM 客户端接口 memory: IMemory; tools: ITool[]; } // 执行一步的结果 export interface IStepResult { thought?: string; action?: { name: string; input: any }; observation?: any; finalAnswer?: string; isComplete: boolean; }4.2 实现第一个可运行的“Hello Agent”我们的第一个里程碑是让一个 Agent 不借助任何工具仅通过 LLM 完成一次简单的问答。实现一个最简单的 LLM 客户端包装(src/llm/clients/OpenAIClient.ts):import OpenAI from openai; import { ILlmClient, ILlmResponse } from ../interfaces; export class OpenAIClient implements ILlmClient { private client: OpenAI; constructor(apiKey: string) { this.client new OpenAI({ apiKey }); } async chatCompletion(messages: any[]): PromiseILlmResponse { const response await this.client.chat.completions.create({ model: gpt-3.5-turbo, messages, temperature: 0.7, }); return { content: response.choices[0]?.message?.content || , raw: response }; } }实现一个简单的缓冲记忆(src/memory/BufferMemory.ts):export class BufferMemory implements IMemory { private buffer: string[] []; private maxSize: number; constructor(maxSize 10) { this.maxSize maxSize; } add(message: string): void { this.buffer.push(message); if (this.buffer.length this.maxSize) { this.buffer.shift(); // 移除最旧的消息 } } getContext(): string { return this.buffer.join(\n); } }组装第一个 Agent 并执行(examples/hello-agent.ts):import { Agent } from ../src/core/Agent; import { OpenAIClient } from ../src/llm/clients/OpenAIClient; import { BufferMemory } from ../src/memory/BufferMemory; async function main() { const llm new OpenAIClient(process.env.OPENAI_API_KEY!); const memory new BufferMemory(); const agent new Agent({ id: hello-agent, name: Greeter, role: 你是一个友好的助手。, llmClient: llm, memory, tools: [] // 暂无工具 }); // 创建一个简单任务 const task { id: 1, description: 向世界问好。, createdAt: new Date() }; console.log(开始执行任务...); const result await agent.execute(task); console.log(Agent 的最终回答:, result.finalAnswer); console.log(完整的执行步骤:, result.steps); } main().catch(console.error);运行这个例子你会看到 Agent 调用 LLM并返回一个问候语。虽然简单但这验证了从配置、记忆到执行的核心链路是通的。这是万里长征的第一步也是后续所有复杂功能的基石。踩坑记录在第一步就遇到了问题。我最初想把所有配置都放在Agent构造函数里但很快发现llmClient、memory这些依赖的初始化可能很复杂需要异步连接。于是我调整了设计要求这些依赖在传入Agent之前就必须是已初始化的实例遵循依赖注入DI原则这让测试和模块替换变得更容易。5. 开发过程中的典型问题与排查实录在构建运行时的过程中我遇到了无数大大小小的问题。这里记录几个最具代表性的以及我的解决思路。5.1 问题一LLM 输出格式不稳定解析失败率高现象在实现 ReAct 引擎时我要求 LLM 以Action: ...\nAction Input: ...的格式输出工具调用。但在实际测试中LLM 有时会输出Action:和Action Input:在同一行有时会漏掉冒号有时甚至会用中文“动作”代替。排查过程增加日志首先我在引擎的_parseLlmOutput方法里加上了详细的调试日志打印出原始的llmOutput字符串。分析模式收集了几十条失败的输出后我发现问题主要出在提示词的指令不够严格且 LLM特别是早期版本或小模型倾向于自由发挥。对比方案我尝试了两种主流方案a) 使用更严格的提示词包括示例Few-shot并威胁“必须严格遵守格式”b) 使用 JSON 格式输出并在提示词中提供 JSON Schema。解决方案我选择了JSON 格式 Zod 验证的组合拳。在提示词中我明确要求 LLM 输出一个 JSON 对象并给出了完整的 Schema 示例。在代码中我用 Zod 定义了这个 Schema并用safeParse方法进行解析。如果解析失败我会将错误信息和原始输出作为新的提示词让 LLM 进行“自我修正”。虽然多了一次 API 调用但极大地提高了系统的鲁棒性。核心代码调整// 在提示词模板中 const systemPrompt ... 你必须以以下 JSON 格式响应 { thought: 你的推理过程, action: 工具名如果没有则为 null, action_input: { /* 工具参数对象 */ }, final_answer: 最终答案如果任务完成则为字符串否则为 null } 请确保输出是有效的 JSON。; // 在引擎中 const ResponseSchema z.object({ thought: z.string().optional(), action: z.string().nullable(), action_input: z.record(z.any()).nullable(), final_answer: z.string().nullable() });5.2 问题二工具调用超时或异常导致整个任务卡死现象当 Agent 调用一个访问外部 API 的工具时如果该 API 响应很慢或挂掉整个执行引擎就会一直等待直到 Node.js 的默认超时可能很长期间这个 Agent 实例无法处理其他任务。排查过程定位阻塞点通过日志发现卡在await tool.execute(input)这一行。分析需求对于工具调用我们需要一个独立的超时控制并且当工具失败时引擎应该能捕获异常并决定下一步动作如重试、更换工具、或向 LLM 报告错误并请求新策略。解决方案为工具管理器引入超时和熔断机制。包装工具调用使用Promise.race为每个工具调用设置一个超时如 30 秒。异常处理用try-catch包裹调用将异常转换为结构化的错误信息作为observation返回给 LLM。熔断器对于连续失败的工具暂时将其标记为“不可用”避免后续任务继续调用它而雪崩。代码示例class SafeToolExecutor { async execute(tool: ITool, input: any, timeoutMs 30000): PromiseToolResult { const timeoutPromise new Promise((_, reject) setTimeout(() reject(new Error(Tool ${tool.name} timeout after ${timeoutMs}ms)), timeoutMs) ); const executionPromise tool.execute(input).catch(e ({ success: false, output: Tool execution failed: ${e.message}, error: e })); try { const result await Promise.race([executionPromise, timeoutPromise]); return { success: true, output: result }; } catch (error) { // 更新该工具的熔断器状态 this.circuitBreaker.recordFailure(tool.name); return { success: false, output: Error: ${error.message} }; } } }5.3 问题三记忆检索引入不相关上下文干扰 LLM 判断现象在实现了基于向量数据库的长期记忆后发现 Agent 有时会做出奇怪的回答。检查日志发现从向量库检索到的“相关记忆”里混入了一些语义相近但主题完全无关的片段导致 LLM 的上下文被污染。排查过程检查嵌入模型确认使用的文本嵌入模型如text-embedding-3-small是否合适。对于中文混合场景可能需要专门的多语言或中文优化模型。检查检索策略当时只是简单取了余弦相似度最高的前 K 条记忆。分析记忆数据发现早期存入的一些记忆文本过于简短或模糊如“好的”、“明白了”这些片段很容易被匹配到。解决方案记忆预处理在将文本存入长期记忆前先让 LLM 对其进行一次摘要或关键词提取只存储信息密度高的内容。避免存储无意义的对话片段。改进检索策略采用“检索后重排序”策略。先用向量检索出 Top N如 20条候选记忆然后使用一个更轻量级但更精准的模型如交叉编码器或基于规则的过滤器如检查是否包含特定实体对它们进行重排序只取 Top K如 3条最相关的。设置相似度阈值为向量检索设置一个最低相似度阈值如 0.7低于此阈值的记忆直接丢弃认为不相关。实操心得记忆系统是“垃圾进垃圾出”。高质量的记忆存入是有效检索的前提。不要盲目存储所有对话历史。同时检索相关性是一个需要持续调优的工程问题没有一劳永逸的方案。6. 性能优化与生产就绪考量当核心功能跑通后我们需要考虑性能和稳定性让这个运行时能从“玩具”变为“工具”。6.1 减少不必要的 LLM 调用LLM API 调用是最大的成本和时间开销来源。优化方向缓存对频繁出现的、结果确定的用户查询或中间推理步骤可以缓存 LLM 的响应。例如使用 Redis 存储(prompt_hash) - response的映射。注意当提示词中带有随时间变化的信息如当前时间时缓存键的设计要小心。流式输出与逐步验证对于长文本生成任务如果可能使用流式 API 并尽早验证生成内容是否符合格式要求可以在中途就中断无效的生成节省 token。小模型优先策略构建一个模型路由层。对于简单的分类、解析任务优先使用便宜快速的小模型如 GPT-3.5-Turbo只有复杂的推理和创作才使用大模型如 GPT-4。6.2 实现异步与并行处理非阻塞 I/O确保所有网络请求LLM、工具 API、数据库都是异步的避免阻塞事件循环。并行工具调用如果 Agent 的一个步骤需要调用多个彼此独立的工具可以并行执行它们使用Promise.all。任务队列与工作线程将耗时的同步计算如复杂的文本处理、本地模型推理放入 Worker Threads避免阻塞主线程。使用外部任务队列如 Bull可以将任务分发到多个进程甚至多台机器上执行。6.3 增强可观测性这是将运行时部署到生产环境的关键。结构化日志使用 Pino 记录 JSON 日志包含agent_id,task_id,step,action,duration_ms,error等字段。方便接入 Logstash、Datadog 等系统。分布式追踪为每个任务生成唯一的trace_id并在所有相关的日志、工具调用、LLM 请求中传递这个 ID。这样可以在复杂的调用链中快速定位问题。指标监控暴露关键指标如任务排队数量、任务处理耗时分布、LLM 调用次数与 token 消耗、工具调用成功率、记忆检索命中率等。可以使用prom-client来提供 Prometheus 格式的指标端点。可视化调试界面理想情况下可以开发一个简单的 Web 界面实时查看任务执行状态、Agent 的思考过程、工具调用流水线等。这对于开发和调试阶段 invaluable。7. 总结与后续规划写到这里这个“造运行时”系列的第一篇也该告一段落了。我们从“为什么造”聊起经历了核心架构设计、技术栈选型、关键模块的深度拆解并动手搭建了一个最简单的可运行骨架还预演了未来会遇到的坑和优化方向。这个过程让我深刻体会到构建一个 Agent 运行时其复杂性不在于某个炫酷的算法而在于对稳定性、可观测性、可扩展性这些传统软件工程问题的扎实解决。Agent 因为引入了非确定性的 LLM让这些问题变得更加突出。我个人在实际操作中的体会是不要试图在第一版就做一个功能完备的框架。应该像剥洋葱一样从最核心、最确定的“执行循环”开始确保它坚固可靠。然后一层层加上记忆、工具、调度等外围功能每加一层都进行充分的测试和重构。同时日志和错误处理要从第一天就开始重视它们是你在迷雾中调试的唯一灯塔。在接下来的系列文章中我计划深入以下几个主题#02: 给引擎装上“手和脚”——工具系统的安全设计与实践详细实现工具管理器探讨沙箱、权限控制、动态加载等高级话题。#03: 让 Agent 拥有“记忆”——从对话历史到向量检索的完整实现实现短期和长期记忆系统并解决记忆检索的相关性难题。#04: 协调的艺术——多任务调度与多 Agent 协作初探实现任务队列并尝试让两个简单的 Agent 通过“黑板”进行协作。#05: 照亮黑盒——可观测性体系构建与实战调试搭建完整的日志、指标和追踪系统并分享几个真实的调试案例。这个项目的所有代码我都会逐步开源。希望这个系列不仅能成为我自己的学习笔记也能成为一个引子吸引更多对 Agent 底层原理感兴趣的开发者一起讨论、贡献。毕竟最好的学习方式就是动手把它造出来。
从零构建AI Agent运行时：架构设计与工程实践全解析
1. 项目概述为什么我要从零造一个 Agent 运行时最近几个月AI Agent 这个概念火得不行从技术社区到产品讨论几乎人人都在谈。作为一个在软件架构和分布式系统领域摸爬滚打了十多年的老码农我本能地对各种“新概念”保持警惕但这次Agent 确实让我坐不住了。不是因为它听起来多酷而是因为我发现市面上现有的那些 Agent 框架、运行时用起来总感觉“隔靴搔痒”。要么是封装得太重像个黑盒出了问题你都不知道从哪查起要么就是太轻只给了你几个 API 和概念剩下的“脏活累活”全得自己来美其名曰“灵活”实则增加了巨大的认知和工程负担。所以我决定自己动手造一个 Agent 运行时。这个决定不是一时冲动而是基于过去几个月里我尝试用各种框架去构建实际业务 Agent 时踩过的无数个坑。比如任务调度混乱导致死锁、记忆管理不当让 Agent“失忆”、工具调用异常时整个流程崩掉却难以定位……这些问题在那些追求“大而全”或“小而美”的框架里往往被隐藏或简化了但恰恰是构建稳定、可靠、可调试的 Agent 应用最关键的部分。我这个项目标题叫“造一个 Agent 运行时 #01:我决定开干,顺便把坑都写下来”。#01 意味着这是一个系列我会把从零开始的设计、编码、测试、优化全过程以及其中遇到的每一个技术决策、每一个踩到的坑都原原本本地记录下来。它不会是一个追求功能最全的“轮子”而会是一个追求“透明”、“可控”和“可学习”的实践样本。我希望通过这个系列不仅能让自己对 Agent 的核心机制有更透彻的理解也能给那些同样被各种框架搞得晕头转向或者想深入理解 Agent 内部工作原理的开发者提供一个可以亲手拆卸、组装的“教学引擎”。简单说这个运行时项目目标用户就是像我一样的实践派开发者我们关心架构的清晰度胜过功能的堆砌关心问题的可调试性胜过接口的华丽度关心核心原理的掌握胜过 API 的简单调用。接下来我会详细拆解我对这个 Agent 运行时的核心设计思路、将要实现的关键模块以及我预见到和已经遇到的那些“坑”。2. 核心设计思路与架构选型2.1 定义我们的“运行时”边界首先我们必须明确“运行时”在这里指什么。在 Agent 的语境下它不是一个像 JVM 或 .NET CLR 那样的通用程序执行环境。我们的 Agent 运行时更准确地说是一个“智能体生命周期管理与任务协调引擎”。它的核心职责是接管一个或多个 Agent 的“大脑”LLM、“记忆”、“工具”和“感知”并驱动它们按照既定策略如 ReAct Chain of Thought去执行任务处理任务执行过程中的状态流转、异常、并发与通信。因此我们的运行时不会去实现 LLM 本身那是 OpenAI、 Anthropic 或本地模型的事也不会去实现具体的工具函数那是开发者的事。我们的焦点在于粘合层和调度层。基于这个定位我画出了第一版的核心架构图在脑海里下文用文字描述Agent 核心Agent Core这是运行时管理的单元。每个 Agent 实例包含身份ID、名称、角色描述、一个 LLM 客户端配置、一个记忆系统引用和一组可用工具。任务队列与调度器Task Queue Scheduler接收外部或内部产生的任务Task将其放入队列。调度器负责从队列中取出任务分配给合适的 Agent 实例执行。这里要处理优先级、超时、重试等策略。执行引擎Execution Engine这是运行时的心脏。它驱动一个任务的完整执行循环。例如对于一个 ReAct 循环引擎需要a) 结合任务描述和记忆构造给 LLM 的提示词b) 调用 LLM 并解析其输出是思考还是调用工具还是最终回答c) 如果调用工具则安全地执行工具函数并获取结果d) 将本轮的结果更新到记忆对话历史或长期记忆e) 判断循环是否继续达到最大步数、LLM 输出最终答案、或出错。记忆管理系统Memory System提供短期如对话上下文窗口和长期如向量数据库的记忆存储与检索能力。运行时需要提供标准的记忆接口并能在执行引擎的适当时机自动调用“保存”和“读取”操作。工具管理器Tool Manager负责注册、发现和管理所有可用的工具函数。它需要提供安全的沙箱环境尤其是对于不可信的工具代码处理工具的输入输出序列化并在工具执行失败时提供清晰的错误信息。可观测性与日志Observability Logging这是调试复杂 Agent 行为的生命线。运行时必须内置结构化的日志记录每一个关键步骤任务入队、调度决策、LLM 请求与响应可脱敏、工具调用与结果、记忆操作、异常事件等。最好能支持 OpenTelemetry 这样的标准方便接入现有的监控体系。2.2 技术栈选型背后的“为什么”选择合适的技术栈是项目成功的基石。我的选型原则是成熟、轻量、可控、社区活跃。编程语言TypeScript/Node.js为什么Agent 生态目前与 JavaScript/TypeScript 结合非常紧密大量的工具、前端集成、云函数部署都围绕此生态。Node.js 的非阻塞 I/O 模型非常适合处理 Agent 任务中大量的网络 I/O调用 LLM API、访问数据库、调用外部 API。TypeScript 的静态类型系统能在编码阶段就捕获大量潜在错误这对于构建一个复杂的、异步的运行时系统至关重要。备选考虑Python 在 AI 领域有统治地位但其在大型并发服务、类型安全尽管有 MyPy和前后端一体化方面我个人觉得不如 TS/Node.js 栈顺手。Go 或 Rust 性能极佳但生态上对于快速集成各种 LLM SDK 和 Web 工具链目前还是 TS/Node.js 更丰富。核心依赖LangChain.js / LangGraph不直接使用其高层 API但会深度参考其设计。LangChain 定义了很好的抽象如BaseChatModel,BaseTool,BaseMemory我们可以实现兼容这些接口的组件这样用户已有的部分 LangChain 工具或记忆体可以无缝接入。更重要的是学习它的设计能避免我们重复造一些基础轮子。Zod用于运行时输入验证和类型推断。在 Agent 系统中LLM 的输出是不稳定的字符串我们需要将其解析为结构化的数据如工具调用参数。Zod 能让我们安全、声明式地定义这些结构并给出清晰的验证错误信息这比手动写if-else强太多。Pino高性能的结构化 JSON 日志记录器。Agent 运行时的日志量会很大结构化日志便于后续通过 ELK 或类似工具进行检索和分析。RxJS / 或自定义 EventEmitter用于实现运行时的内部事件驱动机制。例如“任务完成”、“工具调用开始”、“记忆更新”都可以作为事件发出方便内部模块解耦也便于外部监听进行扩展。存储与外部服务记忆存储短期记忆对话历史可以用内存或 Redis。长期记忆向量检索初期计划支持pgvectorPostgreSQL 扩展和Chroma轻量级向量数据库通过抽象接口实现方便切换。任务队列初期为了简化可能用内存队列或基于 Redis 的Bull库。在生产环境需要考虑更健壮的分布式队列如RabbitMQ或Apache Kafka。注意技术栈不是一成不变的。在系列文章中我可能会因为遇到具体问题而调整选型。例如如果发现 Node.js 的单个进程在复杂推理链中成为瓶颈我们可能会讨论引入工作线程Worker Threads或甚至将执行引擎部分用 Rust 重写为 Native Addon 的可能性。这就是“写下来”的价值——记录决策的演变过程。3. 核心模块深度拆解与实现难点3.1 执行引擎ReAct 循环的稳健实现执行引擎是运行时的核心算法部分。我们以最经典的 ReActReasoning Acting模式为例。一个健壮的 ReAct 引擎需要处理以下关键问题1. 提示词工程与上下文管理引擎需要动态构造每次请求 LLM 的提示词。这包括系统角色设定、任务描述、相关记忆从记忆系统检索、之前的步骤历史思考、行动、观察、以及当前可用的工具列表及其描述。难点在于上下文长度限制。我们需要一个“上下文窗口管理器”当历史超过模型限制时能智能地总结、压缩或丢弃最不重要的部分而不是粗暴地截断。初期实现可能会采用简单的“滑动窗口”法后期再引入更复杂的摘要策略。2. LLM 输出的解析与路由LLM 的输出是一段文本。我们需要从中解析出结构化意图是“思考”Thought: ...是“行动”Action: 工具名\nAction Input: {...}还是“最终答案”Final Answer: ...。这里极易出错。实现方案我们会强制要求 LLM 以严格的格式如 JSON 或特定的分隔符输出。使用 Zod 来定义ToolCall和FinalAnswer的 schema对 LLM 的原始输出进行解析和验证。如果解析失败引擎不能直接崩溃而应进入“修复”流程例如将错误信息和原始输出再次发给 LLM要求其纠正格式。代码示意概念// 定义工具调用响应的结构 const ToolCallSchema z.object({ action: z.string(), action_input: z.record(z.any()) }); type ToolCall z.infertypeof ToolCallSchema; // 在引擎中解析 try { const parsed ToolCallSchema.safeParse(JSON.parse(llmOutput)); if (parsed.success) { // 这是一个工具调用 await handleToolCall(parsed.data); } else { // 尝试解析为最终答案或其他格式... } } catch (error) { // 格式解析失败进入错误处理流程 await handleParseError(llmOutput, error); }3. 工具执行的隔离与安全这是运行时安全性的关键。我们不能让 Agent 随意调用任何系统命令或访问敏感数据。沙箱方案在 Node.js 环境下对于简单、可信的工具如计算器、HTTP GET 请求可以直接执行。对于不可信或高风险工具必须考虑隔离。方案包括a) 使用worker_threads在独立线程中运行b) 使用 Docker 容器运行工具代码c) 通过 RPC 调用部署在安全环境中的服务。初期我们会实现一个基础的SafeToolExecutor它至少会在调用前后进行参数校验和输出过滤并记录完整的调用溯源。4. 循环控制与终止条件引擎必须避免陷入无限循环。我们需要设置明确的终止条件最大迭代步数如 20 步。超时时间如整个任务 2 分钟。LLM 明确输出最终答案。用户手动中断。 引擎需要维护每一步的状态并在每次循环开始前检查这些条件。3.2 记忆系统不仅仅是聊天历史记忆是 Agent 持续学习和保持会话连贯性的基础。我们的记忆系统需要分层设计短期记忆Short-term Memory / Buffer存储当前会话的完整交互历史用户消息、Agent 的思考、工具调用、观察结果。通常受限于 LLM 的上下文长度。实现上可以是一个数组并附带一个“窗口管理器”来处理长度限制。长期记忆Long-term Memory用于存储超越上下文窗口的重要信息并通过语义检索在需要时召回。这通常涉及向量数据库。实现难点如何决定什么信息该存入长期记忆是每轮对话都存还是只存 LLM 认为重要的摘要我们初期会采用一个简单策略在任务结束时由引擎触发让 LLM 对本次任务的关键信息进行总结然后生成嵌入向量存入向量库。检索时将当前问题或上下文向量化从向量库中查找最相关的几条记忆注入到短期记忆的提示词中。记忆的键值对存储除了对话Agent 可能需要记住一些简单的事实如用户偏好user_123.prefers_dark_mode true。我们可以提供一个简单的键值对存储接口底层可以用内存、Redis 或数据库。实操心得记忆系统的设计很容易过度工程化。我的建议是先从最简单的“对话历史数组”开始确保核心执行链路跑通。然后再逐步加入向量检索等高级功能。同时一定要为记忆操作设计详细的日志否则当 Agent 行为诡异时你根本不知道它“记住”或“忘记”了什么。3.3 任务调度与并发处理当有多个任务需要处理或者一个任务可以分解为多个子任务时调度器就至关重要。单 Agent 多任务一个 Agent 实例同时只能处理一个任务。我们需要一个任务队列来管理待办任务。调度器可以采用简单的 FIFO先进先出也可以支持优先级。多 Agent 协作这是更复杂的场景。例如一个“规划者”Agent 将大任务分解然后分配给多个“执行者”Agent。这要求运行时支持 Agent 间的通信。初期我们可以通过一个共享的“黑板”Blackboard系统来实现这是一个共享的键值存储空间Agent 可以将中间结果写在上面其他 Agent 可以读取。并发与资源限制同时向 LLM API 发起大量请求可能会触发速率限制。调度器需要实现一个“令牌桶”或类似的限流机制控制对昂贵资源如 GPT-4 API的并发访问。实现难点状态管理。在分布式环境下任务状态、Agent 状态、记忆状态可能分布在不同的服务或数据库中。如何保证一致性我们初期会以单进程为主状态保存在内存和本地数据库简化这个问题。但架构上要为未来的分布式扩展留出接口例如使用 Redis 作为集中式的状态存储和消息总线。4. 从零开始的实操搭建记录4.1 项目初始化与基础结构搭建首先我们创建一个新的 TypeScript 项目。mkdir agent-runtime-core cd agent-runtime-core npm init -y安装核心依赖npm install typescript ts-node types/node --save-dev npm install zod pino rxjs # 后续会安装 LLM SDK (如 openai) 和向量数据库客户端配置tsconfig.json设置严格的类型检查。然后创建我们的核心目录结构src/ ├── core/ │ ├── Agent.ts # Agent 核心类定义 │ ├── Task.ts # 任务定义 │ ├── Engine.ts # 执行引擎 │ └── Scheduler.ts # 调度器 ├── memory/ │ ├── ShortTermMemory.ts │ ├── LongTermMemory.ts │ └── interfaces.ts ├── tools/ │ ├── Tool.ts # 工具基类 │ ├── ToolManager.ts │ └── builtin/ # 内置工具 ├── llm/ │ └── clients/ # 对接不同 LLM 提供商 ├── index.ts # 主出口文件 └── utils/ └── logger.ts # 日志工具我们先从定义基础接口开始。在src/core/interfaces.ts中// 一个任务的最小定义 export interface ITask { id: string; description: string; // 任务描述 input?: any; // 任务输入数据 priority?: number; createdAt: Date; } // Agent 的配置 export interface IAgentConfig { id: string; name: string; role: string; // 角色描述用于系统提示词 llmClient: ILlmClient; // LLM 客户端接口 memory: IMemory; tools: ITool[]; } // 执行一步的结果 export interface IStepResult { thought?: string; action?: { name: string; input: any }; observation?: any; finalAnswer?: string; isComplete: boolean; }4.2 实现第一个可运行的“Hello Agent”我们的第一个里程碑是让一个 Agent 不借助任何工具仅通过 LLM 完成一次简单的问答。实现一个最简单的 LLM 客户端包装(src/llm/clients/OpenAIClient.ts):import OpenAI from openai; import { ILlmClient, ILlmResponse } from ../interfaces; export class OpenAIClient implements ILlmClient { private client: OpenAI; constructor(apiKey: string) { this.client new OpenAI({ apiKey }); } async chatCompletion(messages: any[]): PromiseILlmResponse { const response await this.client.chat.completions.create({ model: gpt-3.5-turbo, messages, temperature: 0.7, }); return { content: response.choices[0]?.message?.content || , raw: response }; } }实现一个简单的缓冲记忆(src/memory/BufferMemory.ts):export class BufferMemory implements IMemory { private buffer: string[] []; private maxSize: number; constructor(maxSize 10) { this.maxSize maxSize; } add(message: string): void { this.buffer.push(message); if (this.buffer.length this.maxSize) { this.buffer.shift(); // 移除最旧的消息 } } getContext(): string { return this.buffer.join(\n); } }组装第一个 Agent 并执行(examples/hello-agent.ts):import { Agent } from ../src/core/Agent; import { OpenAIClient } from ../src/llm/clients/OpenAIClient; import { BufferMemory } from ../src/memory/BufferMemory; async function main() { const llm new OpenAIClient(process.env.OPENAI_API_KEY!); const memory new BufferMemory(); const agent new Agent({ id: hello-agent, name: Greeter, role: 你是一个友好的助手。, llmClient: llm, memory, tools: [] // 暂无工具 }); // 创建一个简单任务 const task { id: 1, description: 向世界问好。, createdAt: new Date() }; console.log(开始执行任务...); const result await agent.execute(task); console.log(Agent 的最终回答:, result.finalAnswer); console.log(完整的执行步骤:, result.steps); } main().catch(console.error);运行这个例子你会看到 Agent 调用 LLM并返回一个问候语。虽然简单但这验证了从配置、记忆到执行的核心链路是通的。这是万里长征的第一步也是后续所有复杂功能的基石。踩坑记录在第一步就遇到了问题。我最初想把所有配置都放在Agent构造函数里但很快发现llmClient、memory这些依赖的初始化可能很复杂需要异步连接。于是我调整了设计要求这些依赖在传入Agent之前就必须是已初始化的实例遵循依赖注入DI原则这让测试和模块替换变得更容易。5. 开发过程中的典型问题与排查实录在构建运行时的过程中我遇到了无数大大小小的问题。这里记录几个最具代表性的以及我的解决思路。5.1 问题一LLM 输出格式不稳定解析失败率高现象在实现 ReAct 引擎时我要求 LLM 以Action: ...\nAction Input: ...的格式输出工具调用。但在实际测试中LLM 有时会输出Action:和Action Input:在同一行有时会漏掉冒号有时甚至会用中文“动作”代替。排查过程增加日志首先我在引擎的_parseLlmOutput方法里加上了详细的调试日志打印出原始的llmOutput字符串。分析模式收集了几十条失败的输出后我发现问题主要出在提示词的指令不够严格且 LLM特别是早期版本或小模型倾向于自由发挥。对比方案我尝试了两种主流方案a) 使用更严格的提示词包括示例Few-shot并威胁“必须严格遵守格式”b) 使用 JSON 格式输出并在提示词中提供 JSON Schema。解决方案我选择了JSON 格式 Zod 验证的组合拳。在提示词中我明确要求 LLM 输出一个 JSON 对象并给出了完整的 Schema 示例。在代码中我用 Zod 定义了这个 Schema并用safeParse方法进行解析。如果解析失败我会将错误信息和原始输出作为新的提示词让 LLM 进行“自我修正”。虽然多了一次 API 调用但极大地提高了系统的鲁棒性。核心代码调整// 在提示词模板中 const systemPrompt ... 你必须以以下 JSON 格式响应 { thought: 你的推理过程, action: 工具名如果没有则为 null, action_input: { /* 工具参数对象 */ }, final_answer: 最终答案如果任务完成则为字符串否则为 null } 请确保输出是有效的 JSON。; // 在引擎中 const ResponseSchema z.object({ thought: z.string().optional(), action: z.string().nullable(), action_input: z.record(z.any()).nullable(), final_answer: z.string().nullable() });5.2 问题二工具调用超时或异常导致整个任务卡死现象当 Agent 调用一个访问外部 API 的工具时如果该 API 响应很慢或挂掉整个执行引擎就会一直等待直到 Node.js 的默认超时可能很长期间这个 Agent 实例无法处理其他任务。排查过程定位阻塞点通过日志发现卡在await tool.execute(input)这一行。分析需求对于工具调用我们需要一个独立的超时控制并且当工具失败时引擎应该能捕获异常并决定下一步动作如重试、更换工具、或向 LLM 报告错误并请求新策略。解决方案为工具管理器引入超时和熔断机制。包装工具调用使用Promise.race为每个工具调用设置一个超时如 30 秒。异常处理用try-catch包裹调用将异常转换为结构化的错误信息作为observation返回给 LLM。熔断器对于连续失败的工具暂时将其标记为“不可用”避免后续任务继续调用它而雪崩。代码示例class SafeToolExecutor { async execute(tool: ITool, input: any, timeoutMs 30000): PromiseToolResult { const timeoutPromise new Promise((_, reject) setTimeout(() reject(new Error(Tool ${tool.name} timeout after ${timeoutMs}ms)), timeoutMs) ); const executionPromise tool.execute(input).catch(e ({ success: false, output: Tool execution failed: ${e.message}, error: e })); try { const result await Promise.race([executionPromise, timeoutPromise]); return { success: true, output: result }; } catch (error) { // 更新该工具的熔断器状态 this.circuitBreaker.recordFailure(tool.name); return { success: false, output: Error: ${error.message} }; } } }5.3 问题三记忆检索引入不相关上下文干扰 LLM 判断现象在实现了基于向量数据库的长期记忆后发现 Agent 有时会做出奇怪的回答。检查日志发现从向量库检索到的“相关记忆”里混入了一些语义相近但主题完全无关的片段导致 LLM 的上下文被污染。排查过程检查嵌入模型确认使用的文本嵌入模型如text-embedding-3-small是否合适。对于中文混合场景可能需要专门的多语言或中文优化模型。检查检索策略当时只是简单取了余弦相似度最高的前 K 条记忆。分析记忆数据发现早期存入的一些记忆文本过于简短或模糊如“好的”、“明白了”这些片段很容易被匹配到。解决方案记忆预处理在将文本存入长期记忆前先让 LLM 对其进行一次摘要或关键词提取只存储信息密度高的内容。避免存储无意义的对话片段。改进检索策略采用“检索后重排序”策略。先用向量检索出 Top N如 20条候选记忆然后使用一个更轻量级但更精准的模型如交叉编码器或基于规则的过滤器如检查是否包含特定实体对它们进行重排序只取 Top K如 3条最相关的。设置相似度阈值为向量检索设置一个最低相似度阈值如 0.7低于此阈值的记忆直接丢弃认为不相关。实操心得记忆系统是“垃圾进垃圾出”。高质量的记忆存入是有效检索的前提。不要盲目存储所有对话历史。同时检索相关性是一个需要持续调优的工程问题没有一劳永逸的方案。6. 性能优化与生产就绪考量当核心功能跑通后我们需要考虑性能和稳定性让这个运行时能从“玩具”变为“工具”。6.1 减少不必要的 LLM 调用LLM API 调用是最大的成本和时间开销来源。优化方向缓存对频繁出现的、结果确定的用户查询或中间推理步骤可以缓存 LLM 的响应。例如使用 Redis 存储(prompt_hash) - response的映射。注意当提示词中带有随时间变化的信息如当前时间时缓存键的设计要小心。流式输出与逐步验证对于长文本生成任务如果可能使用流式 API 并尽早验证生成内容是否符合格式要求可以在中途就中断无效的生成节省 token。小模型优先策略构建一个模型路由层。对于简单的分类、解析任务优先使用便宜快速的小模型如 GPT-3.5-Turbo只有复杂的推理和创作才使用大模型如 GPT-4。6.2 实现异步与并行处理非阻塞 I/O确保所有网络请求LLM、工具 API、数据库都是异步的避免阻塞事件循环。并行工具调用如果 Agent 的一个步骤需要调用多个彼此独立的工具可以并行执行它们使用Promise.all。任务队列与工作线程将耗时的同步计算如复杂的文本处理、本地模型推理放入 Worker Threads避免阻塞主线程。使用外部任务队列如 Bull可以将任务分发到多个进程甚至多台机器上执行。6.3 增强可观测性这是将运行时部署到生产环境的关键。结构化日志使用 Pino 记录 JSON 日志包含agent_id,task_id,step,action,duration_ms,error等字段。方便接入 Logstash、Datadog 等系统。分布式追踪为每个任务生成唯一的trace_id并在所有相关的日志、工具调用、LLM 请求中传递这个 ID。这样可以在复杂的调用链中快速定位问题。指标监控暴露关键指标如任务排队数量、任务处理耗时分布、LLM 调用次数与 token 消耗、工具调用成功率、记忆检索命中率等。可以使用prom-client来提供 Prometheus 格式的指标端点。可视化调试界面理想情况下可以开发一个简单的 Web 界面实时查看任务执行状态、Agent 的思考过程、工具调用流水线等。这对于开发和调试阶段 invaluable。7. 总结与后续规划写到这里这个“造运行时”系列的第一篇也该告一段落了。我们从“为什么造”聊起经历了核心架构设计、技术栈选型、关键模块的深度拆解并动手搭建了一个最简单的可运行骨架还预演了未来会遇到的坑和优化方向。这个过程让我深刻体会到构建一个 Agent 运行时其复杂性不在于某个炫酷的算法而在于对稳定性、可观测性、可扩展性这些传统软件工程问题的扎实解决。Agent 因为引入了非确定性的 LLM让这些问题变得更加突出。我个人在实际操作中的体会是不要试图在第一版就做一个功能完备的框架。应该像剥洋葱一样从最核心、最确定的“执行循环”开始确保它坚固可靠。然后一层层加上记忆、工具、调度等外围功能每加一层都进行充分的测试和重构。同时日志和错误处理要从第一天就开始重视它们是你在迷雾中调试的唯一灯塔。在接下来的系列文章中我计划深入以下几个主题#02: 给引擎装上“手和脚”——工具系统的安全设计与实践详细实现工具管理器探讨沙箱、权限控制、动态加载等高级话题。#03: 让 Agent 拥有“记忆”——从对话历史到向量检索的完整实现实现短期和长期记忆系统并解决记忆检索的相关性难题。#04: 协调的艺术——多任务调度与多 Agent 协作初探实现任务队列并尝试让两个简单的 Agent 通过“黑板”进行协作。#05: 照亮黑盒——可观测性体系构建与实战调试搭建完整的日志、指标和追踪系统并分享几个真实的调试案例。这个项目的所有代码我都会逐步开源。希望这个系列不仅能成为我自己的学习笔记也能成为一个引子吸引更多对 Agent 底层原理感兴趣的开发者一起讨论、贡献。毕竟最好的学习方式就是动手把它造出来。 
