小节一:工具选错与参数错误——看起来都像“Tool 没干成”,但根因完全不同
很多同学一看到 Tool 没执行成功,就习惯把问题都归成一类。但实际上,“工具选错”和“参数错误”虽然表面都像没干成,排查方向却完全不一样。前者应该先看 Tool Description、能力边界和权限...
小节一:为什么普通日志不够——Agent Trace 需要“结构化执行上下文”
比如 calling tool 这行日志只能告诉我们调用发生过,却不一定能还原模型当时收到的 Prompt、工具参数和结果之间的关系。把普通日志与 Trace 放在一起看,差别会更直观。 右侧强调的是可以沿...
小节三:设计 Trace 数据结构——Run、Step、LLM Event、Tool Event 应该怎么组织
图里可以看到 Run、Step 与其内部 Event 的层级:一次任务下面会有多个步骤,一个步骤里又可能产生 Prompt、LLM Response、Tool Call、Tool Result 和 Metrics 等事件。 这样拆开以后,排查时可...
小节四:实现 TraceRecorder——真正把 AgentEngine、Provider、ToolExecutor 串起来
到代码实现时,最关键的问题是“在哪个组件记录什么”。把 Recorder 的接入点放进一次完整调用链,比单独记住几个 record_*() 方法更容易理解。 Engine 负责步骤与状态,Provider 负责模型请...
小节一:为什么 Agent 会“跑偏”——不是忘了 Prompt,而是长 Run 中局部信息不断覆盖全局目标
很多人会说,“System Prompt 里不是已经写了目标吗?为什么还要 Reminder?” 因为,有一次写进去,不等于几十轮以后仍然保持同样注意力。 尤其 Agent 每一轮都在新增: Tool Result 日志 错误...
小节四:Tool Calling 真正容易踩坑的地方——不是“会不会调用”,而是“能不能可靠执行”
很多 Demo 做到: 模型会输出 Tool Call 就结束了。 但真实工程最难的是,Tool Call 能不能被可靠执行。 至少有六类问题。 先把常见问题集中看一眼,会更容易建立排查顺序。很多时候不是 Tool C...
小节一:直接行动和先规划到底有什么区别——不是“聪明程度”,而是任务结构不同
很多同学一提到 Planner,第一反应是“是不是更高级、更聪明”。其实不是。真正要看的,不是模型聪不聪明,而是任务本身是不是天然带阶段、带依赖、带中间检查点。下面这张图把两种模式并排放在...
案例分析二:Monorepo 里 backend 和 frontend 规则不同,为什么不能只读根目录 AGENTS.md?
再把视角放大到一个同时包含前后端的仓库。图中的根规则只负责共同约定,backend/ 和 frontend/ 各自还有工具链、测试方式和代码规范;Agent 进入不同目录时,应该拿到与目标路径匹配的规则...
案例分析一:Coding Agent 为什么适合拆成 Code Agent + Test Agent,而不是让一个 Agent 自己反复改和测?
这一类案例特别适合用图来建立直觉。一个 Agent 把代码、测试日志、修改历史和问题分析全塞进同一份上下文里,确实能做,但很容易越做越乱。下面这张图就把“单 Agent”和“拆成多个 SubAgent”...
小节五:AGENTS.md 与 Skill、Memory、Middleware 如何协同——项目规则应该进入“行为层”和“执行层”
读到这里,几种信息来源就可以放到一张图里看了。AGENTS.md 给出项目约定,Skill 提供做某类任务的方法,Memory 保留相关历史信息,而 Middleware 在真正调用工具时承担程序化检查。 看图时重...













