query-loop-implementation：把这个 Skill 学会，你的 Agent 循环就稳了

做过 Agent 开发的朋友，一定被”模型调用死循环””工具调用乱飞””上下文无限膨胀”这三座大山折磨过。多数人选择硬编码一堆 if-else 做护城河，结果换个模型又崩了。今天挖到一个极干净的 Skill——query-loop-implementation，用基础设施思维重构 Agent 循环，属于那种看一遍就想立刻用到自己项目里的好东西。

三层架构：别把 Agent 循环当 prompt 写

这个 Skill 最核心的观点就一句：把循环拆成产品基础设施，而不是 prompt 胶水。整个循环被拆成三个明确职责的组件：

• ConversationManager：管状态——session id、消息历史、用户配置、预算限制、持久化。
• QueryLoop：管一次任务轮次——调用模型、检测工具调用、执行工具、append 结果、重复。
• ToolRuntime：管工具注册——schema 定义、权限校验、执行、错误格式化。

三者各司其职，模型负责”思考该调什么工具”，代码负责”确保工具调用可靠执行”。这和 Claude Code 内部的 Agent Loop 思路完全一致。

ReAct 模式的工程化落地

ReAct（Reasoning + Acting）是现在 Agent 循环的主流范式，但多数实现还是拿 prompt 写”请先思考再行动”。这个 Skill 把它做成了结构化 API 流量：

model thinking/text → tool_call → tool_result → next model call → final text

模型输出里检测到 tool_call 就自动走工具流程，append tool_result 消息后再调模型——循环自然闭合，代码比 prompt 版本简洁一个数量级。

六个必须实现的退出条件

Skill 特别强调：上线前必须实现这六种退出条件，否则你的 Agent 可能在生产环境死循环烧钱：

• 正常完成（模型无 tool_call）
• 最大轮次（maxTurns 到期）
• 用户取消 / 超时
• 权限拒绝
• 预算耗尽（token / 费用 / 运行时长）
• 致命工具错误（不可恢复的工具失败）

每种退出都返回结构化的 TerminalReason，不是简单抛异常——方便上游业务做重试或降级逻辑。

工具执行的安全防护

ToolRuntime 对每个工具定义了清晰的契约：schema 校验 → 工具特定校验 → 权限检查 → 执行 → 格式化结果。危险的工具调用会被权限层直接拦截，不会等到执行完才发现问题。

对于可恢复的错误（参数无效、文件不存在、API 临时故障），Skill 的建议是把错误作为 tool_result 返回给模型，让它自己决定是否重试或换策略——而不是直接中断循环。

安装方式

GitHub 仓库 simbajigege/book2skills 已获 162 颗 Stars，安装只需要一行命令：

npx skills add https://github.com/simbajigege/book2skills --skill query-loop-implementation

仓库还附带了 references/query-loop-patterns.md，涵盖完整的 ReAct 模式设计参考，想深入理解背后架构的同学可以细读。

如果你正在做 Agent 化产品，或者想给现有的 LLM 应用加上可靠的 Tool Calling 循环，这个 Skill 值得第一时间收藏。

GitHub 仓库 →

GitHub: https://github.com/simbajigege/book2skills