★ FEATURED ARTICLE 今天围绕 Agent 和 LLM 的讨论几乎把社区热搜霸屏了。有人问 agent 到底怎么开发有人纠结 harness 和 agent 的区别有人跑框架时被 tool payload 报错卡了一下午也有人开始讨论 Spatial LLM、LLM Wiki 这些新概念是不是下一个增长点。这份日报就是把这些散落的关注点按主线收拢适合正在搭 Agent 应用的开发者、想把 LLM 应用边界彻底理清的算法工程师以及准备转行进来的同学。我不会堆术语每个话题尽量把原理、取舍和踩坑记录拆开说清楚。先交代一下我的观察背景最近两周我连续调了两组 Agent 项目一个是多工具调度的研究原型一个是基于本地模型的长期记忆助手。踩过的坑不少正好赶上今天这些热搜词把经验结构化写出来。下面六节按“概念边界、能力扩展、框架编排、故障排查、学习路径、评测方法”展开你可以直接跳到最关心的那节。1. 今日核心观察Agent 与 LLM 的边界到底划在哪1.1 LLM 是大脑Agent 才是会动手的那个人很多人以为 Agent 就是 LLM 套一层提示词今天“agent是什么”这个词条能被搜爆说明这个误解确实普遍。实际上LLM 本身只负责“给定上下文生成下一个 token”的推理它不负责“为什么要做这个动作”“做完之后怎么验证”。而 Agent 是在 LLM 外围套上一个完整的控制循环定义目标、拆分步骤、选择工具、读取结果、失败重试。我用一个生活化类比来解释LLM 像坐在工位上的行业顾问你问什么它答什么但不会主动推进你的项目Agent 像一个项目负责人拿到模糊诉求后自己拆成计划发现缺数据就去找工具要要回来还要校验校验不过再换策略。这个“感知—决策—行动—校验”的循环才是 Agent 的核心价值。今天不少热搜词其实都绕着这个边界打转。比如“agent架构”“agent框架与编排”讨论的是这个循环怎么搭比如“ai agent 怎么扛并发”讨论的是循环跑多了以后资源怎么管再比如“agent 安全”则是在给循环加护栏。理解这个边界之后你会发现很多报错并不神秘比如“agent execution terminated due to error”十有八九是循环里的某个环节超时或步数用尽而不是模型本身“变笨了”。所以第一步不要把 LLM 和 Agent 混为一谈。1.2 Harness 和 Agent先分清“脚手架”和“决策者”热词里“harness和agent区别”能上榜我一点都不意外因为这是项目落到工程阶段后第一个绕不过去的概念。Harness 在 Agent 开发里指的是外层控制骨架负责启动、终止、超时限制、重试策略、日志记录和资源配额。Agent 本体则负责决策我要调用哪个工具、我该如何组织回复、下一步计划是什么。二者之间的关系就像“游戏引擎”和“玩家角色”引擎决定帧循环和崩溃恢复角色决定这一关怎么打。为了让你一眼看出差异我整理了一个维度对比表。维度HarnessAgent核心职责控制循环、生命周期、重试与恢复决策、目标拆解、工具选择状态归属调度状态进行中、暂停、失败推理状态上下文、记忆、计划出问题时的表现超时、进程异常、沙盒更新失败回答跑偏、反复调用同一工具代码上怎么分SDK、框架层、运行环境业务逻辑、工具定义、提示词聊点实操教训我在很多项目里看到开发者把重试、超时逻辑写进 Agent 的 prompt让模型“遇到错误时请重试”。这是典型地把 Harness 的工作塞给模型不仅占用宝贵的 token还让模型在极端场景下反复自我循环最后只能被外部硬杀。正确做法是把超时、重试、资源限制全部交给 Harness 层Agent 只负责在给定约束内做聪明决策。这样排查问题时哪里出错一目了然。1.3 别让“Agent 架构”变成玄学“agent架构”这个词条每次出现都会带来一堆概念焦虑。我的态度很明确架构只是把控制循环落到具体形态的手段不是越高大上越好。现在常见的形态有三种单 Agent 适合任务链路固定、工具少多 Agent 适合子任务解耦、需要并行分层 Agentsupervisor/worker适合需要权限管理、进度汇总的场景。没有最好的架构只有适不适合当前任务的架构。我自己最近做的研究原型就采用了多 Agent 并行处理多个数据源但最后统一由一个“汇总 Agent”收口避免两个 Agent 各自写结论互相矛盾。这个设计的出发点是任务本身有天然并行性而不是为了“多 Agent”而多 Agent。所以我的建议是做架构设计前先把流程图画出来再映射到框架。很多人上来就选 LangGraph文档看半天最后连状态怎么流转都没搞清我先用白板画节点和条件分支再去找框架里的对应机制通常一天就能跑通。流程图里画不出来的环节在代码里大概率也是混乱的。2. Spatial LLM 与 LLM Wiki空间感知和记忆今天讨论最热的两块拼图2.1 Spatial LLM给语言模型装上一副“空间眼睛”“spatial llm”这个词条被高频搜索说明越来越多人在尝试让 LLM 理解空间信息。常规 LLM 把世界当成纯文本符号但很多实际任务需要“地图理解、方位推理、距离估算”这正是 Spatial LLM 要解决的。它通常把坐标、拓扑关系和几何描述编码进训练数据或检索上下文让模型能回答“从 A 走到 B 要往哪个方向”“哪些房间相邻”这类空间问题。落地场景非常具体仓库机器人调度、室内导航、AR 辅助、地理问答。我在自己的实验里发现即使不做专门训练普通 LLM 也可以通过结构化 Prompt 模拟一部分空间推理能力。维护一张“地点—坐标—邻接关系”的表在问答前先检索相关区域再把表塞进上下文模型就能完成简单导航推理。关键是别把整张地图直接扔给它要从坐标里抽取它真正需要的几何关系比如相对方位而不是经纬度数字。这一步抽取得好不好直接决定了空间回答的质量。2.2 LLM Wiki让 Agent 记住“昨天说过的话”“LLM Wiki”这个词条很有意思它指的是以 Wiki 形式组织、面向 LLM 读取的知识库一个条目一个主题每条记录有标题、正文、标签、版本、来源。Agent 在每次对话前根据用户意图去 Wiki 里检索把命中的条目注入上下文。这样做比把整段历史全塞给模型省 token也更方便维护。我自己的长期记忆助手项目就是把这个思路落地了效果比直接塞历史记录好很多。普通向量库会把所有资料无差别切成 chunk而 LLM Wiki 更强调条目化一个页面讲一个概念一个页面讲一个用户偏好。原因在于LLM 的注意力是有限的细碎 chunk 召回后容易丢失上下文逻辑而条目化之后命中单元本身就是一段完整信息回答会聚焦很多。热词里“hermes agent obsidian”把 Obsidian 当知识库背后的思路和 LLM Wiki 是一致的本地 Markdown 页面天然就是条目化知识Agent 通过检索页面来获得记忆可编辑、可追溯、不依赖云端。2.3 Token 记忆的“我是谁、我在找什么、我能提供什么”今天热词里有一句特别精辟“llm的token三个点key我是谁、query我在找什么、value我能提供什么”。这句话几乎是为记忆管理和工具调用设计的。把任何一条上下文或知识条目抽象成三元组会让 Agent 的记忆和检索逻辑清晰很多。key这条信息的身份比如“用户张三的项目偏好”用于去重和索引query我在什么场景下会被需要比如“当用户询问项目排期时”用于召回匹配value实际的内容比如“张三喜欢用看板不接受每日长文汇报”用于注入上下文。这个三元组设计同时适用于 Agent 的记忆管理、工具定义和 RAG 的 metadata 结构。我排查过很多检索失败的工具调用案例最后发现根因几乎都是没有设计好 value 维度工具 schema 里只有参数名没有说明这个参数到底用来回答什么问题或者 query 维度做太粗用户问“排期”时召回了一个讲“风格偏好”的条目结果当然不对。把这三个维度在数据模型里掰开系统行为会立刻收敛。3. Agent 框架与编排今天热搜里的“框架、架构、编排”到底解决什么问题3.1 主流框架怎么选LangGraph、AutoGen 和轻量 ADK今天热词里“llm框架”“agent框架”“spring ai agent”“adk.dev 的 kotlin 快速上手在 jvm 上跑通一个 agent”扎堆出现说明大家正在为选型发愁。我梳理三个主流流派直接给结论。框架核心特点最适合的场景LangGraph显式状态图支持复杂分支和循环链路复杂、需要精细控制状态流转的 AgentAutoGen多 Agent 对话协作开箱即用快速跑多角色 Agent 原型ADKKotlin/JVM轻量JVM 生态、启动成本低已有 Java/Spring 服务、想快速集成 Agent 的团队选型的第一原则是任务驱动。如果业务本质是“一个请求一条流水线”强行用 LangGraph 的图结构纯属给自己加戏普通函数加状态管理反而更清晰如果确实要做并行子 Agent再考虑编排层。我见过太多项目框架选得比业务还复杂最后光维护状态图就把人耗干了。另外如果团队是 Java 背景ADK 是一个非常务实的切入点官方示例从 JVM 上直跑半天就能把 Agent 循环跑通后续还能复用 Spring 生态。3.2 AI Agent 怎么扛并发别让状态成为瓶颈“ai agent 怎么扛并发”这个热词点出了一个多数教程不讲的真实问题。Agent 和普通 API 最大的区别在于它是有状态的交互流程而并发困难恰恰来自状态不是来自模型本身。要做好并发我建议记住三件事。第一外部化状态。把对话上下文和步骤进度放到 Redis 或数据库里不要放在进程内存中。进程重启后状态不丢多实例也能共享同一份进度。第二幂等设计。给每个用户请求生成一个 request_id工具调用也要有唯一编号这样重试时不会重复下单、重复发消息。第三限流与队列。LLM 服务的并发有上限不要期待模型接口能无限扛。给自己加一个信号量或者令牌桶按模型服务的 TPM/RPM 来配置并发数。下面是一个最小骨架展示外部化状态配合信号量的做法import asyncio from aioredis import Redis semaphore asyncio.Semaphore(10) # 最多同时 10 个 LLM 调用 async def run_agent(redis: Redis, user_id: str, request_id: str): async with semaphore: state await redis.get(fagent:{user_id}:{request_id}) # ... 恢复上下文或创建新上下文 # ... 执行推理、调用工具 await redis.set(fagent:{user_id}:{request_id}, new_state)核心原则是“有状态逻辑无状态进程”。另外每个 Agent 实例建议设置单次运行的超时时间和最大步数防止模型陷入无限循环。今天热词里“agent execution terminated due to error”经常就和这类资源限制有关而不是模型能力问题。3.3 可观测性给 Agent 装个“战斗记录仪”Agent 调试比传统接口难因为它的“输出”包括推理链、工具调用、中间结果一长串过程不可见。我强烈建议从一开始就把每个关键节点记为一条 trace至少记录五类信息收到请求时的用户意图每轮 LLM 的完整输入输出每次工具调用的入参、出参、耗时、错误码执行结束时的最终回复token 消耗。我在自己的项目里用结构化日志加一张简易事件表实现这套记录排查问题时真的救命。热词里的“llm request failed: provider rejected the request schema or tool payload.”这类报错如果没有 trace你根本不知道是哪一次工具定义的 payload 被拒。更要命的是Agent 在很多场景下是一次生成多个动作没有 trace 就等于在黑箱里猜。可观测性不是事后补的它是搭建 Agent 时就要具备的基础设施。我给所有准备进场的朋友一个建议哪怕只是本地 demo也把日志结构化不然跑起来之后你会后悔。4. 今天的踩坑实录四个高频报错背后的排查思路4.1 “Agent execution terminated due to error.” 真的是模型不行吗这个报错看起来像模型出问题但实际排查中常见原因是执行体超时、步骤耗尽、工具返回异常。我排查这个报错的顺序固定为三步先看 trace 里最后一个动作是什么是工具调用失败还是模型输出格式异常然后确认是否命中最大步数限制如果是检查 Agent 是不是在反复执行同一个动作最后看超时时间LLM 速度慢时工具等待和 LLM 调用都要单独设超时。有意思的是我遇到过好几回把最大步数从默认的 10 调到 16问题就消失了。因为复杂任务本来就需要更多迭代而默认值往往是从简单 Demo 继承下来的。所以遇到这个报错别急着换更强的模型先看流程是不是卡在同一个工具上。如果确实卡在一个工具上那问题多半是工具描述有歧义模型不知道该返回什么。4.2 “provider rejected the request schema or tool payload.” 是工具定义错了这是今天热词里出现频率极高的报错。它的意思通常是你给模型定义的 function schema 不符合 provider 要求或者模型生成的工具调用参数在校验时失败。常见原因有四种schema 里 required 字段没给全参数类型不匹配比如前端定义为 string模型给成了 integer使用了 provider 不支持的嵌套字段或字段名与保留字冲突多工具同时定义时某些 provider 对工具数量和总体 token 有上限。排查方法很朴素把 provider 收到的 JSON 原样打印出来看。以我的经验最常出问题的反而是“字段描述写得太模糊”。比如一个排序参数叫 filters如果不写清楚每个 filter 的格式模型很容易生成一个结构错乱的 payload。我的做法是每个参数都写一句取值样例比如“filters: [{field: price, op: gt, value: 100}]”模型生成工具的准确率立刻上一个台阶。这条细节属于常规文档里看不到的干货。4.3 客户端报错Codex 无法发送消息和 Agent 沙盒更新失败热词里还有“codex无法发送消息”和“显示更新agent沙盒”这类客户端问题。这类报错通常发生在客户端环境跟模型逻辑没什么关系。我遇到的排查思路是先看本地缓存是不是导致版本不一致清掉工作区缓存再试检查沙盒目录权限尤其 Windows 环境下经常卡在运行目录没有写入权限检查环境变量和 API Key 配置格式很多“发送失败”其实是配置里多了空格或引号这类低级错误只要肉眼过一遍就能发现。这些小问题排起来很快但对新手来说会卡很久因为报错信息根本不会告诉你“权限不足”还是“版本陈旧”。我现在养成的习惯是不管用什么客户端先把所在目录的日志级别调到 debug一次就能定位线索。调日志级别这个动作比到处搜报错文案高效得多。4.4 安卓本地跑 GGUF支持安卓8的选择和量化常识热词“安卓本地运行gguf格式llm软件,支持安卓8”背后是一批希望在隐私敏感场景使用本地推理的开发者。手头有一部旧安卓 8 手机也能跑起来关键是模型选型。GGUF 本质是量化后的模型格式闪存占用小配合 CPU 推理就能在端侧运行。我的建议是手机优先选 2B-7B 的量化模型比如 Q4_K_M内存至少 4GB同时留意发热持续推理很耗电软件可以直接找 llama.cpp 的安卓版或者 PocketPal 这类开源工具导入 GGUF 文件后再选上下文长度。手机端体验和云端 API 还有些差距但做离线演示、隐私数据处理完全够用。这里要提醒一句本地模型同样需要约束工具调用不要让它乱发系统命令否则出了安全问题很难追踪。端侧 Agent 的控制循环该有的限制一个都不能少。5. 从 Skill 到学习路线今天热词里藏着一条完整的 Agent 开发路径5.1 Agent Skill把经验做成可复用的“技能包”热词里“agent skill”“claude agent skills: a first principles deep dive”反复出现说明 Agent Skill 正在成为一套标准化方法。它的本质是把特定任务的提示词、工具调用规范、输入输出校验打包成一个“技能包”。比如“代码评审”这个任务可以定义一个 skill里面包含评审维度、输出格式、需要调用的工具列表、禁止事项。Agent 在需要时动态加载对应技能而不是把所有指令都写进主 prompt。这个做法最大的好处是解耦。主 prompt 只负责当前目标技能包按需加载技能之间不互相污染维护成本低。我在团队里已经把所有复用功能做成了 skill新项目直接引用不再重复写一大段控制指令。如果你正在做多个 Agent 项目强烈建议从今天开始把“提需求—调工具—出结果”的流程拆成独立 skill 文件你会发现项目之间的公共逻辑一下子就能抽出来。5.2 Hermes Agent 与 Obsidian第三方工作台的组合玩法热词“hermes agent obsidian”“hermes agent 第三方工作台”“hermes agent安装”合在一起看其实是一类很实用的工具链。Hermes Agent 我理解上是一个通用的 Agent 管理调度工具而 Obsidian 是本地 Markdown 知识库。把两者结合等于把知识库变成 Agent 的记忆和工具箱在 Obsidian 里维护页面每个页面带明确的 frontmatter 标签Agent 通过检索本地文件来完成任务。这样的好处是知识可编辑、可追溯、数据完全在本地不依赖云端存储。热词“LLM Wiki”“agent画图”“agent skill教程”其实都能在这个工作台上拼起来。想要 Agent 画图就给它配一个绘图工具的 skill想要 Agent 查资料就给它接检索工具。我自己经验是这一类本地方案非常适合写博客、做个人助理、搭内部知识问答。它不会像云端的封装 Agent 那样给你一个漂亮但不可控的聊天框但它的行为模式更可预期、更可调试。安装前先确认版本兼容注意工作目录和调用权限这类工具踩坑点主要在环境配置上。5.3 基于 Rust 和 Kotlin 的 Agent 入门路线今天热词里有“基于rust语言ai agent”“adk.dev 的 kotlin 快速上手在 jvm 上跑通一个 agent”“spring ai agent”三条并排出现满是 JVM 和系统级开发的味道。两条路线我都说点个人判断。Kotlin/JVM 路线适合已有 Spring 服务的团队。用 ADK 最顺直接在 JVM 上起一个 Agent 进程用 REST 接口接入即可优点是和现有服务天然集成部署体系成熟。我给 JVM 背景读者的最小步骤先跑 ADK 仓库的示例把工具定义和 Agent 循环跑通再替换成自己的业务工具半天就能上手。Rust 路线则胜在性能和单文件分发适合做边缘端 Agent 或高并发工具型 Agent。Rust 的框架生态没有 Python 成熟常见做法是直接用 crate 调模型 API自己写 Agent 循环。入门时可以先做一个 CLI 工具实现“LLM 一个函数调用”再逐步加记忆接口。顺带回应热词“基于llm的单元测试”“使用聊天记录模型精调llm”想让 Agent 稳定完成任务先建立“输入样例—预期行为”的回归测试集把每次修复的典型 case 沉淀下来精调是后期手段别在一开始就跳进去。测试集的作用在 Agent 项目里甚至比模型选择更重要它能防止改一个 Prompt 就带崩一片行为。6. 榜单、LLM as Judge 与评测别被公开排名带偏6.1 Open LLM Leaderboard 等公开榜单怎么看热词里有“open llm leaderboard 等公开榜单”这说明大家选模型时还是会先看排名。我的态度是公开榜单可以帮你快速缩小候选范围但别把排名直接当结论。榜单上的评测集和你自己的业务分布往往差很远尤其是 Agent 任务不仅考察模型知识还考察工具遵循、指令理解、格式稳定性这些很难被榜单量化。我的做法分三步先看榜单筛出三到五个候选再用自己的 50 条典型请求做盲测最后选一个在目标任务上错误模式最轻的模型而不是分数最高的模型。还有一条容易忽略的点很多模型的训练数据可能包含公开评测集得分会虚高所以尽量用不公开的私有任务来验收这样得出的结论才接近真实表现。6.2 LLM as Judge让自己的 Agent 学会“自我验收”“llm as judge”指用另一个 LLM 来评估主模型的输出质量非常适合主观判断类任务比如文案、对话、摘要。但 judge 模型不是万能的它同样有偏好和幻觉。设计 judge 的核心是给它清晰的评估标准不能只说“你觉得这个好不好”要给出打分维度和参考样例。比如评价一份 Agent 生成的报告可以从结构完整性、数据准确性、可执行性三个维度打分每个维度写两句话说明。实际操作时我会给每个维度定一个 1-5 分的标尺并附一个“什么样的输出算 5 分、什么样的算 1 分”的示例。另外单次 judge 容易抖动我建议两到三个 judge 模型分别打分后取平均或者做多数投票整体结果会更一致。这套“LLM as Judge”机制其实就是给 Agent 的最终产出装一道质检闸门。6.3 基于 LLM 的单元测试让 Agent 回归测试跑起来最后热词“基于llm的单元测试”值得重点展开。传统单元测试断言输入输出但 LLM 的输出是概率性的没法精确断言所以要做的是“约束性断言”检查输出是否包含特定关键词、是否调用了预期工具、格式是否符合 JSON。我常用的做法是写一个测试用例列表每个用例包含“输入、期望行为、可接受范围”然后用脚本批量跑 Agent最后用 LLM judge 自动判断每个用例是“通过”还是“失败”。这套体系一旦建立后续改 Prompt 或换模型时就能快速验证不会“改一处崩一片”。我在自己的项目里把测试集按业务场景分目录每轮实验跑一遍回归所有行为漂移都能被及时捕获。这也是我能放心调整 Agent 行为模式的原因不是靠记忆而是靠一批可重复执行的检查点。今天这份日报写到这儿如果想让我只留一句经验我会说把 Agent 当成一个需要调试的分布式小系统来对待所有报错先看上下文和 trace而不是急着换模型。这也是我在几个项目里踩了最久的坑换来的结论。后面如果大家想看某一节的展开可以在评论里点题我再单独拆出来写。
阅读完成 · 觉得有帮助？
